現場で役立つAPI設計のポイント集
（1）APIエンドポイントには明確で一貫性のある名前を使う
RESTの原則では、一意のリソースをURLで表現する。そしてリソースとは物や事象を指すので、通常はURLのパス名に名詞を用いる。動詞や短縮形を用いるのは不適切だ。その際、リソースの集合にアクセスするケースが多いので、一般的には名詞の複数型を用いる。
| 良い例 | 悪い例 |
|---|---|
| /products | /getProducts |
| /customers | /cust |
| /orders | /order-info |
| 例外：search（慣用的に使われる） |
より複雑なデータを取得する場合、リソース同士の関係をURLで表現する。その際は、あるリソースの個別IDの後に、関連するリソースのパスを続けるのが一般的だ。例えば、特定の商品についての注文一覧や、顧客が複数の住所を持っている場合の一覧を取得する場合、以下のようなURL形式となる。
| 関係 | 例 |
|---|---|
| 商品の注文 | /products/:product_id/orders |
| 顧客の住所 | /customers/:customer_id/addresses |
APIエンドポイントは適切に抽象化を行う。データベースのテーブル名をそのままURLとして使うなど、実装に依存した構造をAPIに反映するのは避けるべきだ。またページごとに専用のAPIを設けるなど、アプリの用途に特化しすぎる設計も望ましくない。ただし、内部システム向けのAPIで、パフォーマンス向上などの事情が存在する場合は、この限りではない。
（2）必須情報にはパラメータを使い、追加情報にはクエリ文字列を使う
パスパラメータは、特定の製品情報や、特定の顧客情報など、一意のリソースを指定してアクセスする際に使う。例えば、URLでリソースの集合を指定した後に、IDを付与する形で用いる。
| リソース | 例 |
|---|---|
| 特定の製品情報 | /products/12345 |
| 特定の顧客情報 | /customers/23456 |
| 特定の注文情報 | /orders/34567 |
クエリパラメータは、フィルタや並べ替えなど、取得するデータのバリエーションを指定するために用いる。クエリパラメータは省略可能な項目にだけ使い、一意のリソースを表すのに必須の項目に使ってはならない。
| 目的 | 例 |
|---|---|
| フィルタ | /products?category=electronics |
| 並べ替え | /products?price=desc |
| 結果の限定 | /orders?status=pending&limit=10 |
（3）エンドポイントが何をするかに基づいて正しいHTTPメソッドを使用する
エンドポイントで表されるリソースに対してどうアクセスし、どんな操作を行うかを指定するのがHTTPメソッドだ。APIにおいても、HTTPプロトコルの標準仕様に沿って、適切に使用しなければならない。特に、CRUD（Create, Read, Update, Delete）操作は頻繁に行われるため、HTTPメソッドに対応するようにリソースへの操作を行うことが、RESTful APIにおける原則だ。
（4）APIがデータを正しく受け取り、応答できるように設計する
Content-Typeヘッダで、リクエストボディのデータ形式を正しく設定することで、APIサーバが受け取ったデータを適切に解釈でき、また意図したデータが送信されたことを確認できる。逆に、クライアントが受け取りたいデータ形式は、Acceptリクエストヘッダで指定する。レスポンスデータに複数の形式が想定される場合、q（Quality Value）を付与することで、受け取りたい形式の優先度を指定する。サーバはクライアントの希望を考慮して、レスポンスデータ形式を決定する。このようなヘッダでレスポンスデータ形式を指定する方法を、コンテンツネゴシエーションと呼ぶ。ただし、ヘッダを使わず、単にクエリパラメータで形式を指定する方法も、よく使われる。
コンテンツネゴシエーションは、データ形式以外にも、言語指定や、APIのバージョニングにも用いられる。一度公開したAPIを変更する際は、従来の利用者がAPIを使用し続けられるよう、慎重なバージョン管理が必要になる。特に、後方互換性のないmajorバージョンアップについては、一定期間、APIの新旧バージョンを共存させることになるだろう。その際、URLにバージョン番号を組み込むURLバージョニング、クエリパラメータによるバージョニングなどの方法があるが、コンテンツネゴシエーションによる方法が最も柔軟だという。
| 指定方法 | 例 | 説明 |
|---|---|---|
| URLバージョニング | /v1/products | URLにメジャーバージョンを含める |
| クエリパラメータ | /products?price=desc | クエリとしてバージョンを指定 |
| ヘッダ | Accept: application/vnd.api+json;version=1 | コンテンツネゴシエーションを使用 |
適切なステータスコードや、一貫したエラーレスポンスを返すことも重要だ。そうすることで、API利用者が、クライアントに期待されている振る舞いを理解するのに役立つ。原則的にステータスコードは、HTTP標準に準拠するのが望ましい。ただし現実の実装では、さまざまな例外があるので、ステータスコードの細かいユースケースについては、実際のAPIガイドラインを参照するのが良い。またエラーレスポンスについては、RFC 7807という標準仕様が策定されているので、参考にしてほしい。
