REST API設計のベストプラクティス

人々が楽しく使えるREST APIの設計

よく設計されたAPIは使いやすく、予測可能で一貫性があり、期待通りに動作します。REST（Representational State Transfer）はAPI設計で最も一般的なアーキテクチャスタイルであり、その慣例に従うことでAPIの学習、使用、保守が容易になります。

アクションではなくリソースで考える

RESTの中心的な考え方は、APIをリソース（システムが管理するもの、例えばユーザー、注文、製品、記事など）を中心にモデル化することです。各リソースにはそれを識別するURLがあります。HTTPメソッドを使用して行いたい操作を示します：GETは取得、POSTは作成、PUTは置き換え、PATCHは更新、DELETEは削除です。

URLは動詞ではなく名詞にすべきです。/getUsersの代わりに/users、/createOrderの代わりに/ordersを使用します。リソースはネストして関係性を示すことができます：/users/123/ordersはユーザー123に属する注文を表します。これによりAPIが直感的になり、開発者はドキュメントを読まなくてもURLを推測できます。

HTTPステータスコードを適切に使用する

HTTPステータスコードは、クライアントに何が起こったかを伝える方法です。200はすべてが正常に動作したことを意味します。201はリソースが作成されたことを意味し（それを指すLocationヘッダーを含める必要があります）。204はリクエストは成功したが返すコンテンツがないことを意味します。400はクライアントが無効なものを送信したことを意味します。401は認証が必要であることを意味します。403は許可されていないことを意味します。404はリソースが見つからなかったことを意味します。429はレート制限にかかったことを意味します。そして500はサーバーで何か問題が発生したことを意味します。

適切なステータスコードを一貫して使用することで、APIのデバッグがはるかに容易になります。クライアントはエラーメッセージを解析する代わりに、プログラムでエラーを処理できます。HTTPクライアントやAPIライブラリなどのツールは、ステータスコードを理解するとより良いフィードバックを提供できます。

APIを初日からバージョン管理する

APIが完璧だと思っていても、いつかは変更する必要が出てきます。バージョニングにより、既存のクライアントを壊さずに変更を行うことができます。最も簡単な方法は、URLにバージョンを含めることです：/api/v1/users、/api/v2/users。破壊的な変更が必要な場合は、新しいバージョンを作成し、クライアントに移行する時間を与えます。

バージョンが非推奨になったら、レスポンスにSunsetヘッダーを含めて、古いバージョンが最終的に削除されることをクライアントに警告します。これにより、クライアントはアップグレードする時間を得られます。

ページネーション、フィルタリング、並び替えを処理する

APIがリソースのリストを返す場合、クライアントが管理可能なチャンクでデータをリクエストできるように、ページネーションをサポートする必要があります。大規模なデータセットでは、カーソルベースのページネーションがページベースよりもパフォーマンスが優れています。クライアントが一般的なフィールドで結果をフィルタリングできるようにし、並べ替え順序を指定できるようにします。レスポンスにメタデータを含めて、クライアントが次のページを取得する方法を把握できるようにします。

一貫性のあるエラーレスポンスを返す

何か問題が発生した場合、APIはクライアントが解析できる一貫したエラー構造を返す必要があります。エラーコード、人間が読めるメッセージ、問題の詳細を含めます。バリデーションエラーの場合は、どのフィールドが無効でその理由を示します。多くのAPIが従う標準形式としてRFC 7807（HTTP APIの問題詳細）があります。

APIを保護する

認証にはAuthorizationヘッダーでベアラートークン（JWTなど）を使用します。サーバー間通信にはAPIキーを使用します。委任アクセスにはOAuth 2.0を実装します。悪用を防ぐために、クライアントごとにリクエストレートを制限します。そして、監査とデバッグのためにすべてのリクエストをログに記録します。

文書化とテスト

優れたAPIは文書化されています。OpenAPI仕様（旧Swagger）はREST APIを記述する標準的な方法です。ツールはOpenAPI仕様からインタラクティブなドキュメント、クライアントライブラリ、テストスイートを生成できます。契約テストにより、APIが文書化されたとおりに動作することが保証され、モックサーバーによりクライアントはAPIが準備できる前に開発できます。