RESTful API設計ブループリント・ジェネレーター

あなたはStripe、Twilio、GitHubのような企業で、何百万人もの開発者に使われるAPIを設計してきたAPIアーキテクトです。あなたが設計するAPIは、直感的で一貫性があり、開発者にやさしいことで知られています。現実的なニーズに対して実用的でありながら、REST のベストプラクティスに従います。 以下の要件に基づいて、完全なAPIを設計してください： ## プロジェクト要件 APIの目的：[APIが何をするかを記述] 対象ユーザー：[このAPIを使うのは誰か] コアリソース：[主要なエンティティをリストアップ、例：Users, Products, Orders] 認証方式：[API KEY / OAuth 2.0 / JWT / 等] 想定スケール：[秒間リクエスト数 / ユーザー数] ## 完全なAPI設計ドキュメントを生成してください： ### 1. API概要 - APIの名前とバージョン（例：v1） - ベースURL構造の推奨案 - Content-Type（JSONを前提、例外があれば明記） - APIのスタイル（REST、必要であればRPC風エンドポイントについての注記） - レートリミット戦略の推奨案 ### 2. 認証と認可 認証システムを設計してください： - 認証方式の詳細 - トークンの形式とライフサイクル - リフレッシュトークン戦略（該当する場合） - スコープ/権限モデル - 認証ヘッダーの例 ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. リソース設計 各コアリソースについて、以下を定義してください： #### リソース：[名前] - 説明 - 他リソースとの関係 - 一意識別子の形式（UUID、slug、自動採番） **エンドポイント：** ``` GET /[resources] - List all (with pagination) GET /[resources]/:id - Get single resource POST /[resources] - Create new resource PUT /[resources]/:id - Full update PATCH /[resources]/:id - Partial update DELETE /[resources]/:id - Delete resource ``` **データスキーマ：** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... resource-specific fields } ``` **フィールド定義テーブル：** | フィールド | 型 | 必須 | 説明 | 制約 | |-----------|----|------|------|------| ### 4. リクエスト/レスポンス形式 **標準的な成功レスポンス：** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **リストレスポンス（ページネーション付き）：** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **リスト用クエリパラメータ：** - `page` / `cursor` - ページネーション - `per_page` / `limit` - 1ページあたりの件数（最大100） - `sort` - ソート対象のフィールド - `order` - asc/desc - `filter[field]` - フィルタリング - `include` - 埋め込む関連リソース - `fields` - スパースフィールドセット（フィールドの絞り込み） ### 5. エラーハンドリング **エラーレスポンス形式：** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **標準エラーコード：** | HTTPステータス | エラーコード | 説明 | |----------------|--------------|------| | 400 | VALIDATION_ERROR | リクエストの検証に失敗 | | 401 | UNAUTHORIZED | 認証が欠落または無効 | | 403 | FORBIDDEN | 認証は有効だが権限が不足 | | 404 | NOT_FOUND | リソースが存在しない | | 409 | CONFLICT | リソースの状態が競合 | | 422 | UNPROCESSABLE | 構文は有効だが意味的なエラー | | 429 | RATE_LIMITED | リクエストが多すぎる | | 500 | INTERNAL_ERROR | サーバーエラー | ### 6. バージョニング戦略 - URLバージョニング：`/v1/resources` - ヘッダーバージョニングのオプション：`API-Version: 2024-01-15` - 廃止（Deprecation）ポリシー - 移行ガイドのテンプレート ### 7. ページネーション設計 以下から選んで文書化してください： - オフセットベース：`?page=2&per_page=20` - カーソルベース：`?cursor=eyJpZCI6MTAwfQ==` - Keyset：`?after_id=100` 選んだアプローチのメリット・デメリットを含めてください。 ### 8. フィルタリングと検索 クエリパターンを設計してください： ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. レートリミット - レートリミットの階層（プラン/認証レベル別） - 返却すべきヘッダー： - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - 429時のRetry-Afterヘッダー ### 10. WEBHOOKS（該当する場合） - イベントタイプ - ペイロード形式 - 署名検証 - リトライポリシー ### 11. OPENAPI仕様 主要エンドポイントについてOpenAPI 3.0のYAMLを生成してください： ```yaml openapi: 3.0.0 info: title: [API Name] version: 1.0.0 paths: /[resource]: get: summary: List [resources] # ... complete specification ``` ### 12. SDKに関する考慮事項 - 推奨されるSDKパターン - 各言語における慣用的な命名 - エラーハンドリングに関する期待値 - ページネーション用ヘルパー すべての設計を業界標準に沿って一貫性のあるものにしてください。設計上の判断について根拠を示してください。主要なエンドポイントについてはcurlの例を含めてください。