APIの設計において、開発者にとっての使い勝手や、提供者のメンテナンス・拡張のしやすさに配慮することはとても重要です。
記事では、綺麗なAPIを設計するために配慮しておくべき５つのルールが紹介されています。
1. モデル型かアクション型か
REST APIのURLを設計する際、「ユーザー」や「商品」を軸にしたモデル型を採用する場合と、「購入する」「出席する」などの行動を軸にしたアクション型を採用する場合があります。
この際、両方を取り入れると分かりづらいURLとなってしまう懸念があるため、どちらを採用するにしても明確な基準を作っておくとよいでしょう。
2. RESTfulの原則に従う
RESTfulの原則とは、操作する対象のリソースをURLで指定し、CRUD操作をHTTPメソッドで指定するというものです。
たとえばひとつのリソースが複数の状態をもつ場合など管理が煩雑になってしまう際には、コントローラの機能を分離する考え方があります。コードを短縮できますし、操作する対象のリソースをURLで指定、HTTPメソッドで操作というRESTfulの原則が維持できます。
3. バージョンをURIに持たせない
APIのバージョンをURIに入れる場合、バージョンアップした際に旧バージョンで動作するライブラリをコピーする必要が出てきます。
そこで、HTTPヘッダーやクエリストリングの中にバージョン番号を持たせるという方法があります。この方法であれば同じようなコードが増えず管理も楽になります。
4. レスポンスにHALやJSON APIを採用する
JSONだけでは情報が不足する場合には、「HAL」や「JSON API」など情報を付与するフォーマットを採用する方法もあります。
JSON APIはJSONに情報を追加でき、HALはページネーションがある時に次のリンクを示すことができたり、追加のメタデータを付与できます。
ただしAPIのレスポンス変更は簡単ではないため、これから作るAPIでの採用を決めてもよいでしょう。
5. POST/PUTでもレスポンスボディを返す
2回APIにアクセスする必要があるとネットワークに負荷がかかります。
POSTやPUTで更新した最新の状態のデータをレスポンスに含めるようにすることで、クライアントからのリクエストを減らし、負荷を軽減できます。
綺麗なAPIを設計するには気をつけたい5つのポイント | NTT Communications Developer Portal
