dev-api-design

API 設計

このスキルは、REST、GraphQL、gRPC、tRPC、AsyncAPI、エージェント向けインターフェースにおけるコントラクトファーストの API 設計に使用します。コントラクトの選択、認証境界、バージョニング、エラー、ページネーション、レート制限、冪等性、検証を扱います。バックエンドの実装やセキュリティレビューに取って代わるものではありません。

スタイル選択表

API スタイル	選択する状況	避ける状況	標準的な成果物
REST + OpenAPI	公開 API、幅広いツールとの互換性、キャッシュ可能なリソース	ストリーミングを最優先するサービスコントラクト	OpenAPI 3.x
GraphQL	クライアント主導の複雑なクエリ形状、複数チームによるスキーマ所有	シンプルな CRUD、キャッシュが重要、単一チーム	GraphQL SDL
gRPC	内部サービス、双方向ストリーミング、型が重要な境界	公開インターネットの利用者、ブラウザー標準のクライアント	protobuf
tRPC	サーバーとクライアントを共有する TypeScript モノレポ	TypeScript 以外のスタック、公開のサードパーティ利用者	TypeScript 型
AsyncAPI + ウェブフック	イベント駆動型コントラクト、pub/sub、プッシュ通知	同期型のリクエスト／レスポンス	AsyncAPI 3.x
MCP ツールレイヤー	エージェントまたは LLM が主な利用者	人間のみが利用するクライアント	MCP ツールスキーマ

クイックリファレンス

API スタイル	読み込む資料
REST + OpenAPI	references/restful-design-patterns.md、references/openapi-guide.md
GraphQL	references/graphql-patterns.md
gRPC	references/grpc-patterns.md
tRPC	references/trpc-patterns.md
AsyncAPI とウェブフック	references/asyncapi-patterns.md、references/webhook-patterns.md
横断的な基本項目	references/error-handling-patterns.md、references/authentication-patterns.md、references/pagination-filtering.md、references/rate-limiting-patterns.md、references/api-testing-patterns.md

コントラクトレビューのチェックリスト

引き継ぎ前に、すべての API コントラクトについて確認します。

• 標準仕様の成果物が存在する（OpenAPI、AsyncAPI、protobuf、GraphQL SDL、または MCP スキーマ）
• 互換性とバージョニングのモデルが明記されている：進化的変更、URL パス（/v1/）、ヘッダー、またはコンテンツタイプネゴシエーション
• 非推奨化のタイムラインが仕様またはリンク先のドキュメントに記載されている。Deprecation ヘッダーは RFC 9745 の @<unix-seconds> 形式を使用し、Sunset は RFC 8594 に従う
• エラーモデル：REST/HTTP では、安定した type URI と、クライアントが必要とする場合はアプリケーションの code 拡張を含む RFC 9457 Problem Details を使用する。GraphQL、gRPC、イベントでは、それぞれのネイティブコントラクトでエラーを定義する
• 認証境界：各エンドポイントで必要なスコープ、トークンの種類（JWT、opaque）、失効手順
• ページネーション：カーディナリティの高いデータにはカーソルベース、小規模で安定した集合に限りオフセットベースを使用する
• レート制限：IETF httpapi の RateLimit / RateLimit-Policy フィールド、または文書化された従来型の X-RateLimit-* 3 点セットのいずれかを使用する。429 には Retry-After を含める。IETF フィールドはドラフト間で形式が変更されているため、IETF Datatracker で最新版と RFC のステータスを確認し、その改訂版の構文をコピーして、仕様に改訂版を明記する
• 冪等性：POST/PATCH 操作では冪等性キーを文書化するか、明示的に非冪等と記載する。IETF Idempotency-Key ヘッダーのステータスにかかわらず（Datatracker で確認）、仕様でキーのスコープ、保持期間、キー再利用時の応答を定義する
• 長時間実行ジョブ：202 + Location ポーリング URL。終端状態を明記した state 列挙型
• ウェブフック：HMAC 署名、リプレイ保護、ペイロード上の trace_id
• 破壊的変更の検出：oasdiff または同等のツールを CI で設定する
• コントラクトテスト：Schemathesis（プロパティベース）または Pact（コンシューマー主導）を組み込む

ワークフロー

1. 上記の判断表を使って API スタイルを選択します。
2. 正式な契約アーティファクトを定義します。
3. 契約レビューのチェックリストを実施します。
4. 契約の検証、破壊的変更の検出、ドキュメントを追加します。
5. 仕様、例、ロールアウトに関する注意事項を引き継ぎます。

変更クラスごとの互換性の根拠

契約に互換性があると判断する前に、各変更を分類します。

変更クラス	必要な根拠
形状の変更	スキーマの差分に加え、生成されたクライアントのコンパイル、またはコンシューマー契約テスト
形状が変わらない意味的な変更	変更前後の例と、名前を付けた動作に関するアサーション
デフォルト値、順序、クォータ、タイムアウトの変更	本番環境に近いコンシューマーテストとロールアウトに関する注意事項
削除または範囲の縮小	使用状況の根拠、非推奨期間、ロールバックまたは互換性シム

プロバイダーとコンシューマーをデプロイする場合は、メッセージの方向、変更されたペイロード側、実際のコンシューマーの許容度に基づいて、安全な順序を導き出します。新しい任意のリクエスト機能では、コンシューマーがその機能を送信する前に、プロバイダーのサポートをリリースします。レスポンスの列挙値／イベントを拡張する場合、またはコンシューマーが未知のフィールドやバリアントを拒否する可能性がある場合は、新しい値をプロバイダーが出力する前に、未知の値を許容するコンシューマーをリリースして検証します。削除する場合は、先にコンシューマーをリリースし、古いフィールドのトラフィックがなくなったことを確認してから、プロバイダーの動作を削除します。スキーマが追加的であることから安全性を推測するのではなく、関連するコンシューマーの動作を実証してください。スキーマの差分が問題ないだけでは、意味的な互換性やデプロイ順序の根拠として不十分です。

他の参照先

• バックエンドの実装：software-backend
• AppSec レビューと認証の強化：software-security-appsec
• システム全体のアーキテクチャ：software-architecture-design
• ロールアウトと移行の順序付け：dev-workflow-planning

デフォルト

• 実装やコード生成の前に契約を定義します。
• レスポンスボディを必要とする REST/HTTP エラーには RFC 9457 Problem Details を使用し、それ以外の API スタイルではネイティブなエラー形式を定義します。
• バージョニング、非推奨化、冪等性、ページネーション、レート制限を仕様で明示します。
• HTTP またはイベント駆動インターフェースの正式な情報源には OpenAPI 3.x または AsyncAPI を推奨します。パイプライン内のすべてのバリデーター、リンター、ジェネレーターがサポートする最新のマイナーバージョンを固定してください。
• エージェント API は、ランダムなエンドポイントを薄くラップしたものではなく、明確な副作用を持つドメイン契約として扱います。
• エージェントが主要なコンシューマーである場合は、ツール公開レイヤーとして MCP を使用します。その認可モデルは OAuth リソースサーバー標準（RFC 9728 Protected Resource Metadata、RFC 8707 Resource Indicators）を基盤としていますが、セッション、ハンドシェイク、認証の要件は仕様の改訂によって変わります。セッションや initialize ハンドシェイクを前提に設計する前に、modelcontextprotocol.io で現行の改訂版を確認してください。references/llm-agent-api-contracts.md を参照してください。

バージョニング戦略の表

アプローチ	使用する場面	破壊的変更のゲート
URL パスのバージョニング（/v2/）	パブリック API、クライアントのインストール基盤が広い場合	CI で oasdiff --fail-on ERR
ヘッダーのバージョニング（API-Version: 2）	内部 API、頻繁に反復する場合	各 PR で oasdiff
Content-type ネゴシエーション	ハイパーメディアまたはメディアタイプ駆動型 API	手動レビューとテスト
進化的（GraphQL、gRPC）	チームがスキーマを所有し、イントロスペクションツールを実行する場合	GraphQL Inspector / protobuf の互換性

専門家の判断

バージョニング戦略 — チームの好みではなく、クライアントを誰が管理しているかに基づいて選びます。

• すべてのクライアントを管理できない場合（公開 API、サードパーティのインテグレーター、強制更新できないモバイルアプリ）は、実際の利用状況と移行に必要な期間に基づいて、バージョンポリシーとサポート期間を公開します。呼び出し元を予告なく移行させることはできません。
• すべてのクライアントを管理している場合（内部サービスメッシュ、生成クライアントを使うモノレポ）は、バージョニングよりも進化的な互換性（フィールドの追加、非推奨化してから削除）を優先します。新しいバージョン番号は、払う必要のない調整コストです。
• 日付ベースのバージョンは、アカウントやリクエストごとに個別に動作を固定する場合に役立ちます。リクエストでバージョンが省略されている場合は、呼び出し元を予告なくアップグレードするのではなく、文書化された固定のデフォルトに解決し、解決したバージョンをレスポンスヘッダーで返します。
• 「進化的」を互換性ゲートの省略理由にしてはいけません。GraphQL と gRPC でも、CI でスキーマ差分の検査を強制する必要があります（GraphQL Inspector、buf breaking）。「バージョニングしない」は「規律を設けない」という意味ではありません。

ルール：Claude が該当するファイルを編集すると、rules/api/contracts.md によってこの不変条件が読み込まれます。

破壊的変更を検出するための考え方 — スキーマ差分ツールでは構造上検出できないこと：

以下の例はすべて、Hyrum's Law を適用したものです。API の利用者が十分に増えると、文書化されたスキーマだけでなく、観測可能なあらゆる動作が、約束したかどうかにかかわらず事実上の契約になります。（同じ法則を API の表面ではなくスキーマのデプロイ順序に適用した例は、software-database-design/references/migration-strategies.md を参照してください。）そのため、スキーマ差分に問題がなくても、互換性の証明にはなりません。

• 形状を変えない意味上の変更：既存の列挙型で許可される値を絞り込む、以前は寛容だった検証ルールを厳格化する、または型を維持したままフィールドの 意味 を変える、といった変更です。oasdiff／buf breaking では差分なしと報告されます。
• 動作上のデフォルト：デフォルトのソート順、ページサイズ、タイムアウトの変更は、スキーマに変更がなくても、デフォルトに依存する呼び出し元にとって破壊的変更です。
• フィールド間の連動：以前は任意だが無視されていたフィールドが、任意だが適用されるフィールドに変わることです（例：以前は見た目だけだった region フィールドが、ルーティングに影響するようになる）。
• レート制限とクォータの厳格化：スキーマ上の意味での契約違反ではありませんが、削除されたフィールドと同様に本番トラフィックを損ないます。クォータの変更は、フィールド削除と同じ非推奨通知の規律で扱います。
• エラーコードの再分類：あるケースを 404 から 410 に変更したり、汎用の code からより具体的なコードに変更したりすると、Problem Details の形式が変わらなくても、旧コードに基づいてパターンマッチするクライアントが壊れます。
• 自動差分検査（oasdiff、GraphQL Inspector、buf breaking、Pact）は最低限の基準であり、上限ではありません。呼び出し元が実際に何に依存しているかを理解している人による変更履歴のレビューを組み合わせます。

Hyrum's Law の説明は、addyosmani/agent-skills（MIT）、コミット 7676817、2026-08-09 を参考にしています。 GraphQL、gRPC、イベント駆動型コントラクトが不適切な場合：

• GraphQLは、クライアントの形状が1つのシンプルなCRUD、HTTPキャッシュのセマンティクスが必要なチーム（GraphQL-over-HTTP仕様ではPOSTのサポートが必須でGETは任意のため、多くのサーバーはPOSTのみを受け付けます。そのため、HTTPキャッシュにはGETと永続化クエリが必要になります）、そしてクエリの柔軟性によるメリットが得られない単一チーム所有のケースには不向きです。クライアント側のメリットがないまま、N+1のリスク、クエリ複雑度を利用したDoSの攻撃対象領域、フェデレーションツールのコストを抱えることになります。
• ネイティブgRPCは、gRPC-Webまたは互換性のあるトランスポート層を必要とするブラウザクライアントには、デフォルトの選択肢として適していません。サードパーティー向けに公開する場合は、protobufのツールとトランスポートのサポートを考慮してください。幅広いHTTP相互運用性と見つけやすさが重要であれば、REST+OpenAPIを選択してください。
• 呼び出し元が特定のリクエストに対する即時かつ相関付けられた応答を必要とする場合、AsyncAPI／イベントコントラクトは不適切です。リクエスト／レスポンスのワークフローをpub/sub経由にすると、通常の同期HTTPなら避けられる相関IDの管理やタイムアウトの曖昧さが生じます。
• スタイルの選択が適合性ではなく流行によるものだったと判断できる兆候は、選んだスタイルによって解決される具体的なレイテンシ予算、クライアントプラットフォームの制約、または複数チーム間の所有権の問題を、チームの誰も説明できないことです。

よくある落とし穴

• 実際のクライアント、レイテンシ、相互運用性の制約ではなく、アーキテクチャの流行を理由にGraphQL、gRPC、AsyncAPIを選ぶ。
• 重複リクエストや部分的な失敗が発生した場合の、明確な冪等性と再試行の方針を定めずに、正常系のリソースを設計する。
• 実装段階まで認証を暗黙のままにし、エンドポイント間の適用にばらつきが生じる。
• 内部ストレージのセマンティクスが公開コントラクトに漏れるページネーションモデルを再利用する。
• 署名の検証、リプレイ攻撃の防止、コンシューマーのバックプレッシャーがないまま、Webhookやイベントの配信を信頼性の高いプッシュとして扱う。
• 実装後にコードから仕様を生成し、それをコントラクトファーストと呼ぶ。
• 安定した副作用、認証、検証のルールを設けずに、内部の任意のエンドポイントをエージェントAPIとしてラップする。

ナビゲーション

コアパターン：

• references/restful-design-patterns.md — HTTPメソッドのセマンティクス、URL構造、冪等性
• references/pagination-filtering.md — カーソルとオフセットの比較、フィルタリングのコントラクト
• references/error-handling-patterns.md — RFC 9457、エラー分類
• references/authentication-patterns.md — OAuth 2.1、JWT、APIキー、mTLS
• references/rate-limiting-patterns.md — ヘッダー、429への対応、バースト戦略 スタイル別：
• references/api-design-best-practices.md — スタイル横断のDXとガバナンス
• references/versioning-strategies.md — 破壊的変更の検出、非推奨化
• references/api-security-checklist.md — OWASP API Top 10 チェックリスト
• references/graphql-patterns.md — スキーマ設計、フェデレーション、スーパグラフを採用するタイミング
• references/grpc-patterns.md — protobuf 設計、ストリーミング、期限
• references/trpc-patterns.md — TypeScript のエンドツーエンドの型共有
• references/openapi-guide.md — OpenAPI 3.x の作成、リンティング、バンドル
• references/openapi-32-arazzo-101.md — OpenAPI 3.2 で 3.1 に追加された内容（ストリーミング型、QUERY メソッド、OAuth フロー）と Arazzo の複数ステップのワークフローチェーン。複数の API 呼び出しシーケンスを指定する場合や 3.2 の機能を採用する場合に読み込みます
• references/asyncapi-patterns.md — イベント駆動型コントラクト、パブリッシュ／サブスクライブ
• references/webhook-patterns.md — HMAC 署名、リプレイ攻撃対策、配信保証
• references/real-time-api-patterns.md — SSE、WebSocket、ロングポーリングのトレードオフ
• references/api-testing-patterns.md — コントラクトテスト、プロパティベーステスト、Schemathesis
• references/llm-agent-api-contracts.md — MCP 統合、AX 設計、エージェント優先のパターン、LLM コンシューマー向けのルール（集計統計エンドポイント、言語優先の検索、精度制御としてのペイロード削減）

アセットとテンプレート：

• assets/openapi-template.yaml
• assets/spectral-ruleset.yaml — OpenAPI 用のカスタム Spectral リントルールセット
• assets/oasdiff-ci.yml — oasdiff による破壊的変更の検出に使用する CI ワークフロー
• フルスタックフレームワークのスキャフォールド（FastAPI、Express、Django REST、Spring Boot）はコントラクト設計ではなく実装に関するものです。software-backend に移動しました：assets/python/template-python-fastapi-sqlalchemy.md、assets/nodejs-express/template-nodejs-express.md、assets/python-django/template-python-django-rest.md、assets/java/template-java-spring-boot.md
• assets/cross-platform/api-patterns-universal.md
• assets/cross-platform/template-api-governance.md
• assets/cross-platform/template-api-design-review-checklist.md
• assets/cross-platform/template-api-error-model.md
• data/sources.json

関連スキル：

• software-backend、software-security-appsec、data-sql-optimization、qa-testing-strategy、qa-observability、docs-codebase、docs-ai-prd、dev-workflow-planning、software-architecture-design

学びのループ

過去の判断や落とし穴が参考になる場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替ファイルとして使う場合に限り、learnings.md を使用します。それ以外の場合は、どちらも参照しません。

適用後、覚えておく価値のあるパターン、再発防止が必要なミス、または意外だったドメイン知識に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを 1 件追加してください。SKILL.md 自体は変更しないでください。