WebアプリケーションのためのAPI設計原則

API設計原則：開発者が愛するAPIを構築する

適切に設計されたAPIは使っていて楽しいものです。予測可能で一貫性があり、開発者が期待する動作をします。REST API、GraphQL API、その他何を構築するにしても、優れた設計原則に従うことで、APIの学習、使用、統合が容易になります。

一貫性が鍵

API設計で最も重要な原則は一貫性です。命名規則は全体で統一してください — camelCaseかsnake_caseのどちらかにし、両方は使わないでください。すべてのエンドポイントで同じエラーフォーマットを使用してください。すべての場所で同じページネーションアプローチを使用してください。APIの一部を使用した開発者は、別の部分がどのように機能するかを推測できるはずです。

一貫性はエンドポイントの動作にも適用されます。POSTリクエストがリソースを作成する場合、すべてのPOSTリクエストはリソースを作成する必要があります。DELETEリクエストが204 No Contentを返す場合、すべてのDELETEリクエストは204を返す必要があります。予測可能な動作により、APIは直感的になります。

データベースではなくクライアントのために設計する

データベーステーブルに基づいてAPIエンドポイントを設計したくなるものです。しかし、APIはクライアントのニーズに応えるべきであり、データベーススキーマを反映するべきではありません。クライアントが必要とするデータと、それにアクセスする方法を考えてください。モバイルアプリがユーザーのプロフィールと最近の注文を必要とする場合、たとえ異なるテーブルからのデータであっても、両方を1つのレスポンスで返すエンドポイントを提供してください。

これは、複数のソースからデータを集約するエンドポイントを作成することを意味するかもしれません。それで構いません — APIはクライアントの作業を容易にし、困難にしてはいけません。

エラーを優雅に処理する

エラーは避けられません。優れたAPIはエラーを理解しやすく、処理しやすくします。明確な構造を持つ一貫したエラーレスポンスを使用してください。クライアントがプログラムで解析できるエラーコード、人間が読めるメッセージ、そして何が問題だったかの詳細を含めてください。バリデーションエラーの場合は、どのフィールドが無効でその理由を示してください。

HTTPステータスコードを正しく使用してください。ボディにエラーメッセージを入れて200を返さないでください — 不正なリクエストには400、認証失敗には401、認可失敗には403、見つからない場合は404、サーバーエラーには500を使用してください。ステータスコードは、一目で何が起こったかをクライアントに伝えます。

APIをバージョニングする

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

古いバージョンを明確な期限で非推奨にしてください。非推奨のバージョンからのレスポンスにはSunsetヘッダーを含めて開発者に警告してください。非推奨期間が経過した後にのみ古いバージョンを削除してください。

徹底的に文書化する

適切に設計されたAPIは文書化されています。OpenAPI仕様（旧Swagger）はREST APIを文書化するための標準です。これは、インタラクティブなドキュメント、クライアントライブラリ、テストスイートを生成するために使用できる、APIの機械可読な説明を提供します。優れたドキュメントには、例、エラーレスポンスの説明、各エンドポイントのビジネスコンテキストの説明が含まれます。