REST APIについてのお勉強3（&WEB API)(&クラウドやREST以外）


## AWS API Gateway

### 検証ツール

APIGatewayだと公式ツールがあるっぽい。。
開いてみた感じ高機能な気がする。

Postman を使用して、API をテストする - Amazon API Gateway
http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/how-to-use-postman-to-call-api.html

### AWSでのインポート

2015年の記事だけど大枠は参考に。。
多分、今はLambdaの設定もyamlで出来るはず。。

Tips: API Gatewayのエクスポート／インポートでハマったところ - Qiita
http://qiita.com/bageljp@github/items/c4acfe4d0cdf52f293b5

Swagger 定義ファイルを使用して API Gateway API をインポートおよびエクスポートする - Amazon API Gateway
http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/create-api-using-import-export-api.html

試しに作った（拡張書式のない途中のもの）のでやるとエラーが出た。
Swaggerで対応しててもエラーになる箇所があるのね。

![Kobito.Aa8BU6.png](https://qiita-image-store.s3.amazonaws.com/0/18421/babfa449-5287-b874-98e8-0e9d76d25096.png "Kobito.Aa8BU6.png")

amazon web services - AWS API Gateway: Issues with importing Swagger API schema - Stack Overflow
http://stackoverflow.com/questions/39856128/aws-api-gateway-issues-with-importing-swagger-api-schema

jsonにしてからだとだいぶエラーは減るみたい。
そうでもなかった。
認証系のエラーが消えたと思ったら他のが続いて出てきたので一緒だな。

認証はAWSの用意したカスタムオーソリーを使うしかないのかな。
aws側ではswaggerのformDataは対応していないみたい。bodyにしろと。よくわかってない。
コンテンツタイプでformにするかjsonにするかということか。

#### 取り込むと上手くいかないので作ったAPIをエクスポートしてどう出力されているか試して比較して調整する

面倒だな。。
そして、aws以外に適応しにくいんじゃないだろうか。。
認証とか。。bodyとか。。
でも、まあ、確かにフォームデータはbodyになるわけだし、
awsのほうが概念的には指定の仕方は正確なのかな。。

ひとまずawsじゃなくてもいいのかもなあ。。
もうちょっとやってみる。。

swagger側でモデル定義してbodyに紐付ける。。jsonってだけじゃだめなのか。。

### フォームデータの扱い

form,formData,bodyとして書く、とかパターンがありそうで面倒

### パラメータが二つあるときにbodyの定義が難しい。



## 本文マッピングテンプレート

API Gateway + Lambda にFormからPOSTする時のマッピングテンプレートを作成しました ｜ Developers.IO
http://dev.classmethod.jp/cloud/aws/sugano-013-api-gateway/

> API Gateway + Lambda を使った API に対し Form から Post して Lambda に値を渡すにはマッピングテンプレートを登録する必要があります。

### RAML

YAMLベースのREST APIを記述する言語。

WebAPI仕様書を書くためにRAMLを使ってみた - Qiita
http://qiita.com/takizawa-hiroki/items/4613a7520a6f6c6e5cd2

### GraphQL

使い方に気をつければ便利そう。
もっとベストプラクティス的なのが固まってからの方が安心できそうだけどどうなのだろう。

* 関連情報をクライアント側で指定できる。
* 複雑にならないように便利な範囲で使う。
* 1リクエストに縛られるので遅延する。

RESTの次のパラダイムはGraphQLか - Qiita
http://qiita.com/sergeant-wizard/items/f10669e33858543dbc0b

クエリ型のサーバAPIとHTTP2 Server-Pushの組合せについての考察 - Qiita
http://qiita.com/qsona/items/7d33771180b723267da1#_reference-d06924a79449ac62d94f

翻訳: WebAPI 設計のベストプラクティス - Qiita
http://qiita.com/mserizawa/items/b833e407d89abd21ee72#%E8%BF%BD%E5%8A%A0%E6%9B%B4%E6%96%B0%E6%99%82%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%83%9C%E3%83%87%E3%82%A3%E3%81%AB%E3%81%AF-json-%E3%82%92%E4%BD%BF%E3%81%8A%E3%81%86

> 複雑な API に関して言えば、リクエストボディに JSON を使うことにを検討した方が良いです。いずれにせよ、両方採用するようなことはせず、首尾一貫した仕様にしてください。

### bodyに入れるかheaderに入れるか

awsにbodyに入れて渡すとモデル定義する形になるのかどうか、なんか上手く書けずに悩む。
そもそもbodyに入れるべきなのかheaderに入れるべきかがわかってないなあ。。

putの場合には、
bodyに入れるのはリソースだけ、とか、
patchでもリソースをbodyに入れて、置き換え箇所の指定はheaderとか？

PATCH + Swagger
https://community.apigee.com/questions/4794/patch-swagger.html

Using JSON Patch in Swagger
https://aaronsaray.com/2016/using-json-patch-in-swagger

この事例はjsonパッチ。
bodyにpath指定を含むオブジェクトを定義している。


PATCH Method for HTTP
https://wiki.suikawiki.org/n/PATCH%20Method%20for%20HTTP$2215

> PUT との関係#✎
[10]PUT 要求は、 payload body が鯖に蓄積されているものの修正版そのものであり、 蓄積されているものをまるごと置き換えることを求めています。 一方 PATCH 要求は、 payload body が修正版を得るためにどう変更するべきかの指示となっています。 >>6
[23]PATCH の方がかえって PUT よりサイズが大きくなってしまうような場合もあるので、クライアントはどちらが適当か考える必要があります。 >>6
POST との関係
[24]POST はより一般的で、「なんでもあり」なので、 PATCH 相当の操作を POST で行うこともできますし、 実際よく行われています。
[25] 変更したい対象が Request-URI から明確に予測可能でない場合は、 PATCH よりも POST を使うのが適切です。 >>6

うーん、URIで示すようにするほうがいいってことか。。
でも、その場合には構造の指定がサーバーログに残っちゃうってことかな。
リソースとプロパティをごっちゃにするのも嫌なのでわかるような形で指定するのかどうなのか。。

部分置換は難しそうだからやらないほうがいいかしら。

RESTful webサービスを構築しよう | レンタルサーバーのCPIスタッフブログ
http://shared-blog.kddi-web.com/webinfo/205

bodyのオブジェクトでターゲット指定している事例

### とりあえず頭が辛いのでこれでいいや

bodyに入れることにする。

```
  - name: body
    in: body
    description: 設定枠
    required: true
    schema:
      type: object
      properties:
        path:
          description: 構造内パス
          type: string
        contents:
          description: 設定内容
          type: object

```

## ステータスコード

RESTful API設計におけるHTTPステータスコードの指針 - Qiita
http://qiita.com/uenosy/items/ba9dbc70781bddc4a491

うーん、考えるの大変そうだなあ。。

## 認証

Amazon API Gateway で Custom Authorization を使ってクライアントの認可を行う ｜ Developers.IO
http://dev.classmethod.jp/cloud/aws/api-gateway-custom-authorization/

> Custom Authorization の中で最も重要なのが、「Auth Function」と呼ばれる Lambda Function です。API Gateway で作成した API の設定で特定の Lambda Function を Auth Function に指定することができます(設定方法は後述)。この中で独自のロジックで認可する処理を行います。結果として IAM ポリシーの形式で返却すると、API Gateway がそのポリシーに従って認可を実施するという流れになっています。

たぶん、lambdaを介して外部サービスのoauth2とかの認証を実行できるということかしら。。
lambdaは設定する必要があると。。githubの認証のスニペットとかないかしら。