REST APIの設計#
エンドポイント#
https://api.<サービスドメイン>/v<バージョン番号>/<名詞複数形>/:id?<名詞>=hoge
の形が望ましい
ドメイン#
- ドメインは
api.<サービスドメイン>の形にする - 特定の利用者しかいない場合でCORSなどを考慮する場合は
ドメイン/api/としてもよい
バージョン#
- ドメインの後にパスパラメータとしてバージョン識別番号を入れる
- v1,v2のような表記が一般的
パスパラメータ#
- 英語の小文字のみで構成する（スペースやエンコードが必要な文字は使わない）
- 複数形の名詞を用いる
- 複数単語は極力使わない。使う場合はハイフン
-でつなげる
クエリパラメータ#
- 英語の小文字のみで構成する（スペースやエンコードが必要な文字は使わない）
- 複数単語は極力使わない。使う場合はハイフン
-でつなげる - 複数IDを指定したいものは
.繋ぎで指定できるようにするid=aa.bb.cc - 全件数が多いものを取得する場合は、limit(一回の取得数)とoffset(取得開始位置)を利用する
メソッド#
取得 GET
登録 POST
更新（指定データの置換）PUT
更新（指定データの一部を更新）PATCH
削除 DELETE
レスポンス#
- jsonの形で返す
- 必ずトップレベルはオブジェクトで包む（配列で返さない）
- オブジェクト単位でデータ構造を作っておく
- できるだけフラットで階層はすくなく
- トップレベルで決まったキーに入れるなどはしなくていい（URIとメソッドが枠の役割を果たしている）
- 配列は複数形、それ以外は単数系のキー名にする
- キャメルケースにする
- ステータスコードをちゃんと設定する 200,400,500
- エラー時のレスポンスの形は一定にする。 エラーコード、エラー内容が基本