Web API 作成において心得たいことまとめ
最近読んだ書籍「Web API The Good Parts」について個人的に心に留めておきたいことをまとめます. なお, 本書籍は発行年2014年と今となっては若干古いため, 現在では古い情報もあることを念頭において読み進めました.
そのため, 本記事のまとめも今では古いノウハウがあるかもしれません. そういった情報に対してはツッコミをいただけると幸いです.
だいたい, リクエスト, レスポンス, その他といった感じで大まかに3つのセクションにまとめます.
2.2.1 などの数値はそのノウハウが書籍に記載されている章番号です.
リクエストとエンドポイント関連
主に2章の内容.
URI でなんとなく使い方の想像がつく
ドキュメントとかいちいち見たくないため.
http://example.com/v1/user/123 だったら ID 123 のユーザーを取得するみたいに容易に
想像がつく URI が理想.
URI に大文字小文字が混ざっていない
基本はすべて小文字を使用する. ホスト名が大文字小文字を無視するため, ホスト部のルールに足並みを揃える.
エンドポイントには複数形の名詞
2.4.1.1
- users, friends, updates など
- 集合を表しているものは複数形のほうが適切であるという考え
- そもそもなぜ名詞なのか？
- URIがそもそもリソースを表すものであるため
- そして HTTP のメソッドが動詞を表す
エンドポイントの単語のつなぎは「ハイフン」
2.4.4
- 区切り候補
- キャメルケース
- スネークケース
- スパイナルケース
- Google がハイフンを推奨しており SEO 的によいっぽい
- アンダースコアだとリンクアドレスに下線が引かれて重なって見づらい
- URI のホスト部はハイフンは許可されているがアンダースコアは使えず、大文字小文字の区別がないためホスト部とルールを統一するとハイフンとなる
- 実際のところ最も良いのは極力単語を繋げないこと
- パスで区切る
- 短い表現を目指す
- クエリパラメータにする
- しかし割と好みなので、別にアンスコ、キャメルケースでもよい
一括取得系は絞り込みも対応
2.5
GET: /users/ とか
一括取得系のエンドポイントはクエリパラメータを利用して絞り込み 取得などできるとよいかも.
クエリパラメータとパスの使い分け
2.5.5
パラメータをクエリパラメータにするかパスに入れるかの使い分け.
クエリパラメータは以下のような感じのパスの後に?hoge=123などがつく形式.
http://example.com/v1/user/123?hoge=123&fuga=xyz
パスに入れるとは ID 123 のユーザーを取得したい場合は以下のように ID をパスに入れる形式.
http://example.com/v1/user/123
リソースを指定する場合にどちらを採用するかの判断基準は以下.
① 一意なリソースを表すのに必要な情報かどうか
URI がそもそもリソースを表すものであるため, 参照したい情報が一意に決まる場合はパスにしたほうがよい.
② 省略しても良いようなパラメータはクエリにする
メソッド
PUT と PATHCH はどちらも更新系のメソッドだが具体的な使い分けについて.
- PUT
- 2.3.3
- リソースを完全上書きする場合に使用
- 送信するデータでもともとのリソースを完全に上書きする
- PATCH
- 2.3.5
- リソースの一部を修正する場合に使用
エンドポイントの共通部分にバージョンを付与する
2.7
以下の v1 のような感じ.
http://example.com/v1/xxx
レスポンス関連
レスポンスの内容をユーザーが選べるようにする
3.3.1
ユーザーがほしい情報だけを選べるような作りにする. (名前がほしいだけなら名前だけとか) ほしくない情報が含まれるとデータサイズ的にも無駄になってしまう.
クエリパラメータで指定できるようにする.
http://example.com/v1/users/123?fields=name,age
レスポンスデータは配列ではなくなるべくオブジェクトで？
3.3.4
レスポンスデータに配列を使用するかオブジェクトで配列を包むかで 迷った場合はオブジェクトに統一するほうがややオススメ.
読み込んだJSONファイルがオブジェクトの場合, トップレベルにブレースがきて JavaScriptの構文としておかしいためJSONインジェクションを防ぐ可能性がやや上がる.
単/複数形に気をつける
3.4.1
データが複数(配列)になる可能性があるなら「複数形」, 1つだけなら単数形というかたちできちんと使い分ける.
日付はRFC3339を使用する
3.4.3
RFC3339 とは以下のようなフォーマットの日付.
2015-10-15T11:30:22+09:00
- 数ある日時を表すフォーマットの問題を解決したフォーマットだから
- 読みやすく使いやすいを目指したインターネット上で用いる標準形式だから
- 冗長な表現もない
- 他であるような日付と曜日両方を含むなど
ただし, HTTPヘッダの Date や Expires などには使用できない...
エラー時のステータスコードは適切に
3.6.1
ちゃんとステータスコードでエラーの状態を示す. リクエストが成功していないのに200番台を返すなどはしない.
クライアントライブラリとかでステータスコードを見て処理を分岐するものなども あるため, ちゃんと作法に従う.
データをエンベロープ(封筒)で包まない
3.3.2
エンベロープとはAPI的にはすべてのデータを同じ構造でくるむこと.
「HTTPの仕様をフル活用する」にも書いているがそもそもHTTPヘッダがエンベロープなので冗長になる.
その他
HTTPの仕様をフル活用する
4
