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で対応しててもエラーになる箇所があるのね。
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の認証のスニペットとかないかしら。