API設計 は何をしますか？
実装の前に契約を設計しましょう。
使用するタイミング
以下の場合に使用します：
- ユーザーが新しいAPIやインターフェースを設計する場合
- 既存の契約を変更する場合
- リクエスト/レスポンススキーマを定義する場合
- エラーハンドリング、認証、ページネーション、バージョニングをレビューする場合
- サードパーティサービスと統合する場合
- 「このエンドポイントはどうあるべきか？」と質問された場合
1. 契約の明確化
以下の項目を特定します：
- APIを呼び出すのは誰か：フロントエンド、モバイル、サービス、パートナー、エージェント
- 呼び出し元が達成する必要があるもの
- 入出力されるデータ
- 呼び出し元が絶対に参照してはいけないもの
- レイテンシ、容量、信頼性の要件
- 互換性とバージョニングの制約
2. リソースとアクションのモデル化
- リソースには名詞を使用し、CRUD以外の操作には明示的なアクションを使用します。
- URLは安定しており、予測可能に保ちます。
- 一つのことを行う明確な方法を一つだけ優先します。
- データベース構造を公開契約に漏洩させないようにします。
- 識別子、所有権、テナンシーを定義します。
3. スキーマの定義
各エンドポイントまたはインターフェースについて：
- メソッドとパス
- 目的
- 認証と権限
- パス、クエリ、ボディパラメータ
- 検証ルール
- 成功レスポンス
- エラーレスポンス
- 冪等性
- ページネーション
- レート制限
- 例
4. エラーの設計
すべてのエラーには以下を含める必要があります：
- 安定した機械可読コード
- 人間可読なメッセージ
- 原因となったフィールドまたはパラメータ
- サポート用のリクエストID
- スタックトレース、シークレット、内部パスは含めない
一貫したHTTPステータスコードを使用します。失敗した操作に対して200を返さないでください。
5. セキュリティとプライバシー
- 公開されていないすべてのエンドポイントを認証します。
- ルートレベルだけでなく、オブジェクトレベルで認可します。
- 境界ですべての入力を検証します。
- 呼び出し元が必要とするフィールドのみを返します。
- 情報が漏洩する可能性がある内部IDを公開しないでください。
- レート制限と不正利用制御を定義します。
- Webhookを信頼できない入力として扱います。
6. 進化可能性
- フィールドの意味を変更するのではなく、フィールドを追加します。
- クライアントが移行するまで古いフィールドを保持します。
- 必要な場合にのみバージョニングします。
- 非推奨と移行を文書化します。
- マイナーリリースでの破壊的変更を避けます。
7. 出力フォーマット
## 契約
### `METHOD /path`
**目的:** <何をするか>
**認証:** <誰が呼び出せるか>
**冪等性:** <はい/いいえ と キー>
#### リクエスト
| フィールド | 型 | 必須 | ルール |
|---|---|---|---|
#### レスポンス
```json
{}
```
#### エラー
| ステータス | コード | 発生条件 |
|---|---|---|
#### 例
```http
METHOD /path
...
```
## 互換性
- <変更可能なもの>
- <新しいバージョンが必要なもの>
## 未解決の質問
- <質問>
ルール
- ビジネスルールを発明しないでください。
- 理由なく内部フィールドを公開しないでください。
- エンドポイント間で一貫性のない命名を使用しないでください。
- 現在のデータベーススキーマを中心に公開APIを設計しないでください。
- エラーや空の状態の動作を省略しないでください。
- APIが金銭、健康、個人データを扱う場合は、セキュリティレビューを要求してください。
品質チェック
- 呼び出し元とジョブが明確である。
- スキーマが完全である。
- エラーが一貫しており安全である。
- 認証とオブジェクトレベルの権限が定義されている。
- ページネーションと制限が定義されている。
- 互換性が考慮されている。
- 例が有効である。