【まとめ】Web API: The Good Partsを呼んで重要だと思ったこと
オライリーの書籍「Web API: The Good Parts」を読んで、重要だと思ったことのまとめ。
個人の感想も含んでいます。
エンドポイントの基本的な設計（リクエスト）
エンドポイントの設計で一般的に重要とされていること
- 短くて入力しやすい
- 人間が読んで理解しやすい
- むやみに短縮形を使わない
- product→prod、week→wkなど
- japan→jpなど、省略形が浸透しているものやPJで統一されている場合はそれに従った方がいいことも。
- 大文字小文字が混在しない
- 改造しやすい（Hackable）
- https://yone-himajin.com/api/users/12345
- ユーザーID「12345」にアクセスしていることが予想できる
- サーバ側のアーキテクチャが反映されていない
- サーバサイドがphpなのかjavaなのかはエンドポイントには不要な情報
- ルールが統一されている
- HTTPメソッド（GET、POSTなど）をエンドポイントで表現するのは冗長
- https://yone-himajin.com/api/users/get、https://yone-himajin.com/api/users/postとするのではなく
- https://yone-himajin.com/api/usersにGET、POSTでアクセスしたときにサーバサイドの処理が変わるように設計する
エンドポイント設計の注意点
- 複数形の名詞を使う（users、booksなど）
- スペースやエンコーディングは使用しない
- 単語をつなげる時はハイフン（-）が無難
- キャメルケース、スネークケースなどが使われているサービスもあるので、ハイフンが正解とは一概には言えない。
検索処理の注意点
- 検索処理でユーザーが1万人以上いるような場合、全てのユーザーを取得するAPIしかないと処理が重い
- ページネーションを実装することで一回の取得上限を設ける
- 相対的な取得位置を使う場合、データ量が増えると処理が重くなるので注意
- 先頭から何件目かを調べるために、RDBではORDER BYが走ることが予想される
- IDや日時の絶対位置でデータを取得することで相対位置の問題を回避できる
- IDや名称などの条件で絞り込めるAPIも用意しておく
レスポンスデータの設計
- データフォーマットはJSONがデファクトスタンダード
- 特定のニーズがあった場合に、XML、その他の形式を検討する
- APIのアクセス回数が少なくなるようにすべき
- ユーザーIDだけを返すようなAPIの場合、データのサイズ「少なくすることはできる。
- ただし、ユーザーIDだけを必要とする場合は少なく再度APIにアクセスする可能性がある
- 必要だと思われるデータを全てレスポンスに載せる方法
- リクエストでほしいデータを指定させる方法
- データをフラットにすべきか、階層化すべきか
- なるべくフラットにした方が良いが、階層化した方が分かりやすい時もある
- エンベロープをすべきかどうか
- エンベロープとはheader、responseのように区分けすること
- 配列にするかオブジェクトにするか
- 配列の件数、続きがあることをどうするか
- 例えば100件あるデータの20件だけを返した時
- 続きのデータがあること、合計が100件という情報を載せるか
- エラーの表現
- 404、500などのステータスコードでエラーを表現できる
- ステータスコードで表現できないエラーは、詳細情報を載せる
設計変更のしやすいAPI
- URIにバージョンをつける
- バージョンを変更するときは後方互換性を維持する
- セキュリティや権限に関する修正が入った時は後方互換性を保てないかもしれない
