今回は、こういった疑問に答えします。
以下のWeb API The Good Partsという書籍を参考に、Web API開発のコツを質問（Q&A）形式でまとめてみました。
これからWeb API設計をしようと思っている方の参考に少しでもなれば幸いです。
- Web API設計のポイントをQ&A形式でまとめてみた
- Web APIのエンドポイント（URI）の命名はどんなことを意識すればいい？
- PUT,POST,PATCHの使い分けを教えてください
- URIのリソース名は複数形にすべき？それとも単数系にすべき？
- URIのリソース名で単語を繋げる必要がある場合はどうすればいいのでしょう？
- パスにするかクエリパラメータにするかはどう切り分けたら良いのでしょう？
- APIのレスポンスのデータフォーマット何を採用すべきでしょうか？
- APIのレスポンスデータの構造を決める上でのポイントを教えてください！
- 複数データを返す場合、配列をそのまま返すべきでしょうか？それとも配列をオブジェクトで包んで返すべきでしょうか？
- レスポンスの各データのフォーマットはどうすべきでしょうか？
- レスポンスでエラーを返す際のポイントを教えてください！
- APIのバージョニング方法について教えてください！
- Web API設計のポイントをQ&A形式でまとめてみた:おわりに
Web API設計のポイントをQ&A形式でまとめてみた
それでは、Web API設計のポイントをQ&A形式でまとめていきます。
Web APIのエンドポイント（URI）の命名はどんなことを意識すればいい？
基本的には、「覚えやすく、どんな機能を持っているかが分かりやすいURI」が良いURIと言えるでしょう。
具体的な良いURIの特徴は以下の通りです。
- 短く入力しやすい
- 人間が読んで理解できる
- むやみに省略形を使わない
- 小文字のみが使われている
- 使い方を理解しやすい（ex：/items/123 は123がitemのidだと想像しやすい）
- サーバー側のアーキテクチャ（使っている言語など）が反映されていない
- エンドポイント間でルールが統一されている
PUT,POST,PATCHの使い分けを教えてください
以下のように使い分けると良いでしょう。
- POST・・・新規リソースの作成
- PUT・・・データの更新（元々のリソースを完全に更新する）
- PATCH・・・データの更新（元々のリソースの一部を更新する）
URIのリソース名は複数形にすべき？それとも単数系にすべき？
基本的には複数形にすべきです。
なぜなら、URIはリソースの「集合」を表しており、そこに対してリクエストを送ってデータを取得するイメージだからです。
DBのテーブル名で複数形が推奨されているのと同じようなイメージを持つと良いでしょう。
URIのリソース名で単語を繋げる必要がある場合はどうすればいいのでしょう？
特に絶対的なルールがあるわけではありませんが、基本的にはハイフンで繋ぐのが良いでしょう。
なぜなら、URLのドメイン名では、ハイフンは使えますがアンダースコアなどは使えないからです。
ハイフンを使うことでURL全体の統一感を高めることができます。
パスにするかクエリパラメータにするかはどう切り分けたら良いのでしょう？
基本的な判断基準は以下の通りです。
- 一意のリソースを表すのに必要かどうか
- 省略可能かどうか
例えばユーザーidなどは、それを指定すれば取得するリソースが一意に定めるため、パスにすべきです。
一方で、limitやoffsetなどはそれを指摘してもリソースが一意に定まるわけではないため、クエリパラメータにすべきです。
APIのレスポンスのデータフォーマット何を採用すべきでしょうか？
基本的にはJSONを使うのが良いでしょう。
なぜなら、もはや世の中のAPIのデファクトがJSONになっているからです。
もはや他のものを選択する理由はほとんどないです。
APIのレスポンスデータの構造を決める上でのポイントを教えてください！
ポイントは以下の通りです
- なるべくAPIのアクセス回数が抑えられるようにする
- ex：ユーザーidだけでなくユーザーの名前などの情報も含めて返す
- エンベロープ（全てのデータを同じ構造で包む）は行わない
- 冗長な表現であるため（HTTPがエンベロープの役割を果たしている）
- HTTPのヘッダにステータスコードなども入っている
ちなみに「情報を過不足なく取得してAPIへのアクセス回数を減らす」という意味では、新しいAPIの形式である、GraphQLも最近のトレンドの一つです。
以下に基本をまとめたので、ぜひ参考にしてみてください。
複数データを返す場合、配列をそのまま返すべきでしょうか？それとも配列をオブジェクトで包んで返すべきでしょうか？
どちらでも問題はありませんが、以下の理由からオブジェクトで包むことを推奨します。
- 配列に対するキーがあることで何のデータかが分かりやすくなる
- レスポンスデータをオブジェクトに統一できる
- セキュリティ上のリスク（JSONインジェクション）を避けることができる
レスポンスの各データのフォーマットはどうすべきでしょうか？
基本的にはキャメルケースにすべきです。
なぜなら、JSONではキャメルケースを使うのが良いとされており、JSONがベースとしているJavaScriptの命名規則においてもキャメルケースがの利用が推奨されているからです。
レスポンスでエラーを返す際のポイントを教えてください！
ポイントは以下の通りです。
- 適切なステータスコードを返す
- エラーの詳細をBodyで返す
- エラーの詳細には以下を含める
- エラーの詳細コード（HTTPステータスコードではない。API提供側でエラーごとに付けたもの）
- エラーメッセージ（開発者向け・ユーザー向け）
- ドキュメントページのURI
必要十分な情報をクライアントに返して、クライアントが再度APIを使えるようにサポートすることが重要です。
APIのバージョニング方法について教えてください！
急な仕様変更によりAPIを利用するクライアントに混乱を与えないためには、APIを適切にバージョン管理することが重要です。
バージョン管理することにより、以前のエンドポイントは残し続けたまま、新たなエンドポイントを公開することができます。
バージョン管理には以下のような方法があります。
- 別のURIでAPIを公開する
- URIにバージョン情報を埋め込む
基本的には、以下のようにURIにバージョン情報（v2）を埋め込むのが良いでしょう。
https://api.com/v2/sample
Web API設計のポイントをQ&A形式でまとめてみた:おわりに
今回は、Web API設計のポイントをQ&A形式でまとめてみました。
以下のWeb API The Good Partsは、API設計の基本が詰まった圧倒的な良書です。
この記事で紹介した項目以外にも、多くのWeb API設計のコツがまとめられています。
API設計をする可能性がある全てのエンジニアが手元に持っておくべき書籍と言えるでしょう。
