api-design

API 設計

このスキルは、曖昧な統合アイデア、バックエンド機能、またはサービス境界を、ほかのスキルが土台として利用できる安定した API コントラクトにまとめるために使います。

目的は、見栄えのよいドキュメントを作ることではありません。目的は次のとおりです。

• 問題に適した API スタイルを選ぶ
• リソース、操作、入力、出力、失敗時のセマンティクスを定義する
• 互換性とバージョニングに関する判断を明確にする
• 実装、テスト、ドキュメントで共有できるコントラクト成果物を作成する
• チームが誤ったインターフェースを固定化する前に、トレードオフを明らかにする

通常とは異なる API 作業やリスクの高い API 作業に取りかかる前に、references/contract-review-checklist.md と references/boundary-guide.md を読んでください。

ユーザーが主に必要としているものが次の場合は、

• リファレンスドキュメント、チュートリアル、サンプルを豊富に含むガイド、またはドキュメントポータルのセットアップ → api-documentation を使います
• 認証の実装、またはトークン／セッションの設定 → authentication-setup を使います
• コントラクト／統合テストの戦略 → backend-testing を使います
• スキーマ／インデックス／ストレージの設計 → database-schema-design を使います

このスキルを使う場合

• 新しい REST API、GraphQL スキーマ、または内部サービスのコントラクトを設計する
• クライアントを不必要に壊さずに既存の API をリファクタリングする
• 命名、リソース境界、ステータスコード、ページネーション、フィルタリング、冪等性、またはエラーモデルをレビューする
• 実装開始前に OpenAPI または GraphQL SDL コントラクトを作成する
• バージョニングと後方互換性に関する判断を評価する
• API を REST のままにするか、GraphQL に移行するか、両方のレイヤーを意図的に公開するかを決める
• バックエンド、フロントエンド、QA、またはパートナーチーム向けに、実装にすぐ使えるコントラクト一式を準備する

このスキルを使わない場合

• 主な作業が、インタラクティブなドキュメント、SDK ドキュメント、オンボーディングガイド、またはサンプルポータルの作成である → api-documentation を使います
• 主な作業が、サーバーコード、認証ミドルウェア、リゾルバー、または永続化ロジックの記述である
• 主な作業が、データベースの正規化、インデックス作成、またはストレージモデルの最適化である → database-schema-design を使います
• 主な依頼が、テスト計画またはコントラクトテストのカバレッジに関するものである → backend-testing を使います
• API の形を正確に定義できるほど明確になっていない。この場合は、確実であるかのように装うのではなく、未解決の質問を明示し、設計スパイクを提案します

手順

ステップ 1：コントラクト上の課題を整理する

エンドポイントを考案する前に、設計の入力情報をまとめます。

次の項目を記録します。

• API を呼び出すユーザーまたはシステム
• ビジネス上の操作、または達成すべき作業
• ドメインエンティティと所有権の境界
• 互換性を制約する既存クライアントまたは移行
• 機密性／セキュリティ要件
• 想定される規模のパターン：読み取り、書き込み、ファンアウト、ページネーション、バースト性
• 要求される成果物の形式：OpenAPI、GraphQL SDL、エンドポイント表、または設計メモ

依頼の内容が不十分な場合は、設計資料の中で不足している前提を明示します。

ステップ 2：インターフェースのスタイルを慎重に選ぶ

慣れだけを理由に、特定のスタイルを既定の選択肢にしないでください。

次の場合は REST を優先します

• ワークフローがリソース中心である
• キャッシュ、予測しやすい URL、またはシンプルな CRUD 形式の操作が重要である
• 外部クライアントに、安定した標準的な HTTP セマンティクスが必要である
• OpenAPI ツール、モック、幅広いエコシステムとの互換性が必要である

次の場合は GraphQL を優先します

• クライアントが柔軟なフィールド選択や、複数のグラフを組み合わせたたどり方を必要としている
• フロントエンドチームが、多数の画面にわたる過剰なデータ取得や不足するデータ取得を減らす必要がある
• 固定されたエンドポイント一覧より、スキーマのほうが共有コントラクトとして適している
• スキーマレジストリや破壊的変更のチェックをすでに導入している、または導入する見込みがある

次の場合に限り、混合アプローチを優先します

• それぞれの責務が明確に異なる
• どのチームがどのインターフェースを、なぜ利用するのかを説明できる
• 所有権の重複や乖離を防げる

選択したスタイルの理由を明記します。「みんなが使っているから」では不十分です。

ステップ 3：モデルリソース、操作、境界

REST の場合：

• 最上位のリソースと、それぞれの所有権の境界を定義します
• 動詞のエンドポイントではなく名詞を選びます。ただし、アクションエンドポイントのほうが明確な場合は例外です
• ネストしたリソースに明確な親子関係がある場合を除き、URL 構造は浅く保ちます
• 標準操作とドメイン固有のアクションを分けて列挙します

GraphQL の場合：

• 中核となる型、関係、クエリ、ミューテーションを定義します
• 何でも受け付ける巨大なミューテーションの集まりは避けます
• ページネーション、フィルタリング、フィールド単位の認可が適用される箇所を記載します
• 頻繁に変更される可能性が高いスキーマ領域を特定します

どちらの形式でも：

• 同期動作と非同期動作を明示します
• 冪等な書き込みと非冪等な書き込みを特定します
• 関連する場合は、結果整合性や長時間実行されるジョブの動作を明記します

ステップ 4：リクエスト／レスポンスの契約を定義する

正常系だけでなく、契約を設計します。

以下を含めます：

• リクエストの形式と必須フィールド
• 成功時のレスポンス形式
• ページネーションまたはカーソルのルール
• フィルタリング／ソートのセマンティクス
• null 許容性とデフォルト値
• フィールドの命名規則
• タイムスタンプ、ID、列挙型の動作
• 部分更新の動作

API がマシン間通信クライアントとフロントエンドクライアントの両方に対応する場合は、レスポンス形式や展開パターンが異なる箇所を記載します。

ステップ 5：認証、エラー、互換性のルールを設計する

クライアントが依存する運用上のセマンティクスをまとめます。

以下を定義します：

• 契約レベルでの認証モデルの要件（例：ベアラートークン必須、ロールチェック、テナントのスコープ設定）
• 一般的なステータスコード／エラーカテゴリ
• 機械可読なエラーコード
• 再試行／冪等性に関する要件
• 非推奨化と提供終了の動作
• 互換性の保証：追加のみで安全、破壊的変更、バージョンによる制御、または移行が必要

ここでは認証を完全に実装しないでください。契約を定義し、必要に応じて詳細な設定を authentication-setup に引き継ぎます。

ステップ 6：契約成果物を作成する

後続作業を可能にする範囲で、最も簡潔な成果物を選びます。

推奨形式：

• OpenAPI アウトライン：REST 契約や、レビューを重視する環境向け
• GraphQL SDL のスケッチ：スキーマファーストの GraphQL 作業向け
• エンドポイント／操作の表：初期のアーキテクチャ議論向け
• 設計メモ＋リスクリスト：適切な形式についてまだ議論中の場合

最小限の契約パケット：

• 選択した形式とその理由
• 対象読者／利用者
• エンティティまたは型のマップ
• 操作とリクエスト／レスポンスの概要
• 認証／エラー／バージョニングに関する注記
• 未解決の質問／リスク
• 後続作業への引き継ぎ先

ステップ 7：破壊的変更と引き継ぎの品質を確認する

最終確定の前に、以下を確認します：

• 既存のクライアントに破壊的な影響がないか
• 命名とセマンティクスに一貫性があるか
• ページネーション／フィルタリングのルールは実際に実装できるか
• エラー状態と認証失敗は、フロントエンド／QA／ドキュメント作業に十分明確か
• 契約の設計と、チュートリアルの執筆やサーバー実装を誤って混同していないか

次の作業への引き継ぎ先を明確にします：

• 公開ドキュメント、チュートリアル、例、ドキュメントポータルの設定には api-documentation
• 契約テストと統合テストの計画には backend-testing
• 具体的な認証の実装には authentication-setup
• ストレージモデルに個別の検討が必要な場合は database-schema-design

出力形式

## API Design Packet: [Name]

### Contract framing
- Style: [REST | GraphQL | mixed-with-justification]
- Consumers: [internal services / frontend app / partners / public developers]
- Primary job: [what the API enables]

### Resource or type model
- [resource/type]: [purpose]
- [resource/type]: [purpose]

### Operations
| Operation | Purpose | Input summary | Output summary | Notes |
|-----------|---------|---------------|----------------|-------|
| [GET/POST/query/mutation] | ... | ... | ... | ... |

### Contract rules
- Auth model: [...]
- Error model: [...]
- Pagination/filtering: [...]
- Versioning / compatibility: [...]

### Risks / open questions
- [...]

### Handoffs
- Documentation: [does `api-documentation` need to turn this into published docs?]
- Testing: [does `backend-testing` need contract/integration coverage?]
- Auth / data model: [adjacent handoffs]

例

例 1：パートナー連携向けの公開 REST 契約

入力：「EC ベンダー向けに、パートナーが利用する注文ステータス API を設計してください。安定したポーリングと、後日の Webhook フォールバック、慎重なバージョニングが必要です。」

望ましいレスポンスの形式：

• 外部パートナーには予測可能な HTTP セマンティクスが必要なため、REST を選択する
• orders と order-events を明確に定義する
• ステータス遷移、ページネーション、更新時刻によるフィルタリング、バージョニング／非推奨化のルールを指定する
• 機械可読なエラーコードと、冪等性を考慮した Webhook 登録の要件を含める
• パートナー向けドキュメントと例について、api-documentation に引き継ぐ

例 2：ダッシュボードクライアント向けの GraphQL スキーマ

入力：「プロジェクト、デプロイ、インシデント、アラート向けのダッシュボード API が必要です。UI には多くのビューがあり、REST ではデータを過剰に取得し続けています。」

望ましい応答の形：

• 柔軟なクライアント読み取りに GraphQL を選ぶ理由を説明する
• コアとなる型とクエリ／ミューテーションの境界を定義する
• ページネーションとフィールド／クエリレベルでの認可について言及する
• スキーマの負荷が集中しそうな箇所と、破壊的変更のレビューが必要な点を指摘する
• コントラクトチェックは backend-testing に、クエリ例は api-documentation に引き継ぐ

ベストプラクティス

1. API コントラクトを、単なるコード上の利便性ではなく、プロダクトの境界として扱います。
2. 設計上の決定とドキュメントの公開を分けます。
3. 確実であるかのように装わず、前提と未解決の質問を記録します。
4. 予期せぬ破壊的変更ではなく、追加による進化と明示的な非推奨化を優先します。
5. REST と GraphQL のどちらを選ぶ場合も、その根拠を明確にします。
6. 後続チームが作業を進められる、最小限の成果物を使います。
7. このスキルに詰め込みすぎず、隣接するスキルへ意図的に引き継ぎます。

参考資料

• OpenAPI 仕様
• GraphQL のベストプラクティス
• Microsoft REST API ガイドライン
• Zalando RESTful API ガイドライン
• アーキテクチャ決定記録