api-design

API 設計

REST／GraphQL のフレームワーク設計、バージョニング戦略、RFC 9457 によるエラーハンドリングを網羅した API 設計パターンです。各カテゴリには個別のルールファイルがあり、必要に応じて rules/ から読み込まれます。

クイックリファレンス

カテゴリ	ルール	影響度	使用する場面
API フレームワーク	3	HIGH	REST の規約、リソースのモデル化、OpenAPI 仕様
バージョニング	2	HIGH	URL パスによるバージョニング、ヘッダーによるバージョニング。廃止までの期間は references/ork-delta.md にあるプロジェクト内ポリシーです
エラーハンドリング	1	HIGH	エージェント向け RFC 9457 拡張。基本仕様と FastAPI の接続方法は上流資料を参照してください
GraphQL	2	HIGH	Strawberry によるコードファースト設計、DataLoader、権限、サブスクリプション
gRPC	2	HIGH	Protobuf サービス、ストリーミング、インターセプター、再試行
ストリーミング	2	HIGH	SSE エンドポイント、双方向 WebSocket、非同期ジェネレーター
インテグレーション	2	HIGH	メッセージングプラットフォーム（WhatsApp、Telegram）、Payload CMS のパターン

合計：7 カテゴリにわたる 14 個のルールです。 削られたファイルから救済されたプロジェクト内の決定事項は references/ork-delta.md にあります。ベンダー資料と仕様は再掲せず、リンクしています（上流資料の対象範囲を参照）。

API フレームワーク

一貫性があり、開発者にとって使いやすい API を実現するための REST および GraphQL API 設計規約です。

ルール	ファイル	主なパターン
REST の規約	rules/framework-rest-conventions.md	複数形の名詞、HTTP メソッド、ステータスコード、ページネーション
リソースのモデル化	rules/framework-resource-modeling.md	階層型 URL、フィルタリング、ソート、フィールド選択
OpenAPI	rules/framework-openapi.md	OpenAPI 3.1 仕様、ドキュメント、スキーマ定義

バージョニング

クライアントに互換性を損なう変更を加えずに API を進化させるための戦略です。

ルール	ファイル	主なパターン
URL パス	rules/versioning-url-path.md	/api/v1/ プレフィックスによるルーティング、バージョン別スキーマ
ヘッダー	rules/versioning-header.md	X-API-Version ヘッダー、コンテンツネゴシエーション

廃止と提供終了については、プロジェクト内の期間（3 か月前の通知、6 か月後に提供終了、現行バージョンと次の 1 バージョンをサポート）を references/ork-delta.md に記載しています。ヘッダーの仕組みについては上流資料を参照してください（RFC 8594、RFC 9745）。

エラーハンドリング

機械可読で標準化されたエラーレスポンスのための RFC 9457 Problem Details です。

ルール	ファイル	主なパターン
エージェント向けエラー	rules/errors-agent-facing.md	エージェント向け拡張：retryable、error_category、コンテンツネゴシエーション、トークン効率

RFC 9457 の基本形式、FastAPI の例外ハンドラーの接続方法、Pydantic の 422 マッピングについては上流資料を参照してください（上流資料の対象範囲を参照）。ここではプロジェクト固有の内容として、Problem Details のタイプ URI 規約と型付き例外の用語を references/ork-delta.md に、完全に動作する実装を examples/fastapi-problem-details.md に記載しています。

GraphQL

型安全なリゾルバーと FastAPI 統合を備えた、Strawberry GraphQL のコードファーストスキーマです。

ルール	ファイル	主なパターン
スキーマ設計	rules/graphql-strawberry.md	型安全なスキーマ、DataLoader、共用体エラー、Private フィールド
パターンと認証	rules/graphql-schema.md	権限クラス、FastAPI 統合、サブスクリプション

gRPC

内部マイクロサービス間通信に適した、高性能な gRPC です。

ルール	ファイル	主なパターン
サービス定義	rules/grpc-service.md	Protobuf、非同期サーバー、クライアントのタイムアウト、コード生成
ストリーミングとインターセプター	rules/grpc-streaming.md	サーバー／双方向ストリーミング、認証、再試行のバックオフ

ストリーミング

SSE、WebSocket、および適切なクリーンアップによるリアルタイムデータのストリーミングです。

ルール	ファイル	主なパターン
SSE	rules/streaming-sse.md	SSE エンドポイント、LLM ストリーミング、再接続、キープアライブ
WebSocket	rules/streaming-websocket.md	双方向通信、ハートビート、aclosing()、バックプレッシャー

インテグレーション

メッセージングプラットフォームとのインテグレーションと、ヘッドレス CMS のパターンです。

ルール	ファイル	主なパターン
メッセージングプラットフォーム	rules/messaging-integrations.md	WhatsApp WAHA、Telegram Bot API、Webhook のセキュリティ
Payload CMS	rules/payload-cms.md	Payload 3.0 のコレクション、アクセス制御、CMS の選定

クイックスタートの例

# REST endpoint with versioning and RFC 9457 errors
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse

router = APIRouter()

@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: str, service: UserService = Depends()):
    user = await service.get_user(user_id)
    if not user:
        raise NotFoundProblem(
            resource="User",
            resource_id=user_id,
        )
    return UserResponseV1(id=user.id, name=user.full_name)

主な決定事項

決定事項	推奨事項
バージョニング戦略	公開 API には URL パス（/api/v1/）を使用します
リソースの命名	複数形の名詞と kebab-case を使用します
ページネーション	大規模なデータセットにはカーソルベースを使用します
エラー形式	application/problem+json を使用する RFC 9457 Problem Details
エラータイプ URI	独自の API ドメインに /problems/ プレフィックスを付けます
サポート期間	現行バージョンとその 1 つ前のバージョン
非推奨の告知	サポート終了の最低 3 か月前
サポート終了までの期間	非推奨化から 6 か月後
GraphQL スキーマ	Strawberry の型を使ったコードファースト
N+1 の防止	すべてのネストしたリゾルバーで DataLoader を使用します
GraphQL の認証	権限クラス（コンテキストベース）
gRPC proto	ファイルごとに 1 つのサービスを定義し、common.proto を共有します
gRPC ストリーミング	リストにはサーバーストリーム、リアルタイム通信には双方向ストリームを使用します
SSE のキープアライブ	30 秒ごと
WebSocket のハートビート	30 秒ごとに ping-pong を行います
非同期ジェネレーターのクリーンアップ	すべての外部リソースに aclosing() を使用します

よくある間違い

1. URL に動詞を含める（POST /users ではなく POST /createUser）
2. エンドポイント間でエラー形式に一貫性がない
3. バージョンを上げずにコントラクトを変更する
4. Problem Details ではなくプレーンテキストでエラーを返す
5. 非推奨化ヘッダーなしでバージョンをサポート終了にする
6. エラーに内部の詳細（スタックトレース、DB エラー）を公開する
7. エラーレスポンスに Content-Type: application/problem+json がない
8. 同時にサポートする API バージョンが多すぎる（最大 2～3）
9. バージョン間の分離を考慮せずにキャッシュする

上流のカバレッジ（再記述しないこと）

2026-07-31 の wrap-plus-delta による削減で削除されたトピックです。一次情報を参照してください。このスキルに含めるのは ork 差分（社内ポリシー、教訓、実運用設定）のみです。

トピック	一次情報
RFC 9457 Problem Details の仕様（メンバー、メディアタイプ、about:blank、クライアント側のパース）	https://www.rfc-editor.org/rfc/rfc9457.html
FastAPI の例外ハンドラー、Pydantic の検証エラー（422）、エラーカタログの定型コード	https://fastapi.tiangolo.com/tutorial/handling-errors/
API のバージョニング戦略のチュートリアルと FastAPI のバージョン別ルーター解説	https://fastapi.tiangolo.com/tutorial/bigger-applications/
Deprecation ヘッダーと Sunset ヘッダーの仕組み	https://www.rfc-editor.org/rfc/rfc8594.html および https://www.rfc-editor.org/rfc/rfc9745.html
汎用 REST リファレンス（メソッド、ステータスコード、ページネーション形式、認証ヘッダー）	https://www.rfc-editor.org/rfc/rfc9110.html および https://developer.mozilla.org/en-US/docs/Web/HTTP
OpenAPI 3.1 仕様の作成（テンプレートは assets/openapi-template.yaml に残っています）	https://spec.openapis.org/oas/v3.1.0
gRPC proto のスタイル、サービス定義、ステータスコード	https://grpc.io/docs/ および https://protobuf.dev/programming-guides/style/
Payload CMS のコレクション設計、フィールド型、アクセス制御	https://payloadcms.com/docs
フロントエンドでの API 利用（Zod による境界検証、ky、TanStack Query）	https://zod.dev および https://tanstack.com/query/latest/docs
API 設計／エラー処理／バージョニングのレビューチェックリスト	上記の仕様から導出できます。チェックリストの再記述は含めていません

評価

すべてのカテゴリにわたる 13 件のテストケースについては、test-cases.json を参照してください。

関連スキル

• fastapi-advanced - FastAPI 固有の実装パターン
• rate-limiting - 高度なレート制限の実装とアルゴリズム
• observability-monitoring - バージョン使用状況のメトリクスとエラートラッキング
• input-validation - API エラー処理以外のバリデーションパターン
• streaming-api-patterns - リアルタイム API 向けの SSE と WebSocket のパターン

機能の詳細

rest-design

キーワード： rest、restful、http、endpoint、route、path、resource、CRUD 解決する課題：

• RESTful API はどのように設計すればよいですか？
• REST エンドポイントのパターンと規約
• HTTP メソッドとステータスコード

graphql-design

キーワード： graphql、schema、query、mutation、connection、relay 解決する課題：

• GraphQL API はどのように設計すればよいですか？
• スキーマ設計のベストプラクティス
• ページネーション向けの Connection パターン

endpoint-design

キーワード： endpoint、route、path、resource、CRUD、openapi 解決する課題：

• API エンドポイントはどのように構成すればよいですか？
• このリソースにはどの URL パターンが最適ですか？
• RESTful エンドポイントの命名規約

url-versioning

キーワード： url version、path version、/v1/、/v2/ 解決する課題：

• REST API はどのようにバージョン管理すればよいですか？
• URL ベースの API バージョン管理

header-versioning

キーワード： header version、X-API-Version、content negotiation 解決する課題：

• URL をすっきりさせるバージョン管理
• ヘッダーベースの API バージョン管理

deprecation

キーワード： deprecation、sunset、version lifecycle、backward compatible 解決する課題：

• API バージョンはどのように廃止すればよいですか？
• バージョンのサポート終了ポリシー
• 破壊的変更と非破壊的変更

problem-details

キーワード： problem details、RFC 9457、RFC 7807、structured error、application/problem+json 解決する課題：

• API のエラーレスポンスを標準化するにはどうすればよいですか？
• API エラーにはどの形式を使えばよいですか？

agent-facing-errors

キーワード： agent error、AI agent、retryable、retry_after、error_category、content negotiation、accept header、token efficient、machine readable 解決する課題：

• AI エージェントの利用者向けエラーレスポンスはどのように設計すればよいですか？
• エラーレスポンスのトークンコストを削減するにはどうすればよいですか？
• エラーをエージェントが確定的に処理できるようにするにはどうすればよいですか？
• エージェント、ブラウザー、LLM 向けのコンテントネゴシエーション

validation-errors

キーワード： validation、field error、422、unprocessable、pydantic 解決する課題：

• API のバリデーションエラーはどのように処理すればよいですか？
• フィールド単位のエラーレスポンス

error-registry

キーワード： error registry、problem types、error catalog、error codes 解決する課題：

• すべての API エラーをどのように文書化すればよいですか？
• エラータイプの管理