Web API: The Good Partsまとめ

参考になった事をあとで振り返る用として。

概要

Web APIの設計、開発、運用についての解説書

PUTメソッド

• リソースを完全に更新する
  

p:32

PATCHメソッド

• リソースのごく一部を更新する
  

p:32

エンドポイント名で単語を繋げる際はハイフンを使う

• ハイフンはGoogleが単語繋ぎとみなすがアンダースコアはひとつづきとみなすし、みづらい
• そもそも、極力繋がない表現にするのが良い
  

p:41

ページング系のクエリパラメータは絶対位置の方が良い

• 相対位置の問題点はレコードを先頭から数えるためデータが増えると遅くなること。また、更新頻度が高いとズレが生じる
• 絶対位置とはIDや作成日時を指定する条件として使用することで、最終取得時の先端・末端レコードのIDや作成日時を保持し、次の情報はその保持したデータを元に参照すること。
  
• FacebookのAPIなどがそうなっているので参考にすると良い

P:44, 45

OAuth2.0

• あるサービスの情報を別のサービスで利用できる仕様。トークンを元に利用できる
• トークンには他のユーザーが利用できないように有効期限が設けられる

p:49, 50, 51

レスポンスの内部構造はなるべくフラットな方が良い

• データサイズが大きくなるし、必要以上な階層による表現は不要
  

p:80

ステータスコード

よく使いそうなステータスコード

ステータスコード	名前	意味	ケース
200	ok	リクエスト成功	参照
201	Created	リクエストが成功し、新しいリソース作成	登録
204	No Content	コンテンツなし	更新、削除
301	Moved Permanently	リソースが恒久的に移動	リダイレクト(キャッシュあり)
302	Found	リソースが一時的に移動	リダイレクト(キャッシュなし)
400	Bad Request	リクエストが正しくない	不正リクエスト
401	Unauthorized	承認が必要	認証エラー
403	Forbidden	アクセスが禁止	アクセス制限
404	Not Found	指定したリソースが見つからない	参照エラー
409	Conflict	リソースが矛盾した	排他制御
429	Too Many Requests	リクエスト回数が多すぎる	回数制限
500	Internal Server Error	サーバエラー	処理落ち
503	Service Unavailable	サーバが一時的に停止	同時アクセス制限

p:103

プリフライトリクエストはOPTIONメソッドを使う

• プリフライトリクエストとは生成元を跨ぐリクエストの受け入れチェックのこと
  https://qiita.com/rooooomania/items/4d0f6275372f413765de

p:132

オーケストレーション層を作る考え方

• 下記2タイプのAPIの特性から、データ量を調整する層を設けるとメンテし易い
  • 外部公開用のAPI(LSUDs)
    • 汎用的な設計のため単体目的の情報のみ返す傾向
  • 内部的運用のAPI(SSKDs)
    • 運用のユースケースに合わせた設計にするため複数目的の情報を含める傾向
      

P:153

リクエスト再送信

• 繰り返しアクセスによる問題有無を判断し、リクエスト再送信を防ぐ。
  • ユニークなトークンなどを事前に保持する(サーバー側はセッション、クライアント側はhiddenなど)
  • トークンが合致すれば正常処理、合致しなければ不正処理とする
  • 決済や回数計測などで使用する

p:176

書籍情報

水野 貴明. Web API: The Good Parts
https://amzn.to/2wy6DQy