Web API 設計のお作法を学ぶスクラップ
とんよー。Web API 設計のお作法
基本
予測可能であること
API は主となる機能が 1 つのみである事が望ましい。
（例えば、あるデータAを削除する API なら、データ削除の挙動のみとする。）
もし主となる機能以外の機能を実装するなら、予測可能な挙動であること。また、ドキュメントやコメントアウトにその挙動を明記すること。
（例えば、あるデータAを削除する API において、削除対象とリレーション関係にあるデータBを削除するなど。）
パスはシンプルであること
無用に長いパスは避けること。
リソース名は複数形であること
基本的にデータベースのテーブル名に準拠すれば OK。テーブル名に紐づかない場合であってもリソース名は複数形とする。
例
Request と Response の形式は統一性があること
API α と API β のパラメータやレスポンス形式は統一すること。
形式を統一するのは当然に、数値型の単位なども気をつけること。
「ない」の表現を統一すること
リソースが「ない」ことをどのように表現するか決めておくこと。
例えば、配列のリソース・パラメータの場合、リソースがない = 空配列であるとして、null や undefined はどのような意味をなすか、方針を決めておくこと。
デフォルト値を明快にすること
Requset パラメータのデフォルト値は事前に決めておくこと。
「パラメータを明示的に設定しない場合に、デフォルトを XX にする」とか
「すべてのパラメータが必須であり、欠けることは許容しない」とか
方針は実装したい内容に寄るが、デフォルト値の方針は決めておくこと。
メソッドは適切に設定すること
GET, POST, PUT, DELETE, … を適切に設定すること。
なんどもかんでも GET, POST にしようとしない！
- GET: リソースの取得
- POST: リソースの新規作成
- PUT: リソースの更新
- DELETE: リソースの削除
- …などなど
リソースの量は適切に分割すること
リソースの取得・更新には上限値を設けること。
また、Request パラメータで上限値以上のリソース数を指定したとしても、上限値までの操作に留めること。
データベースに大きな負担がかかってしまうため。よくある offset と limit みたいなヤツ。
バージョニング
いくつかのパターンがあるが、いずれの場合でも簡潔にバージョンを表現できていること
URL バージョニング
- ルートから分けるパターン: https://example.com/api/v1/users
- コントローラー別に分けるパターン: https://example.com/api/users/v1/update
パラメータによるバージョニング
Http Request において、Header や Body のパラメータにバージョンを含める。
バックエンドでは、バージョン情報を元に処理を切り分ける。
排他処理
- WIP
キャッシュ
- WIP
アンチパターン
- WIP