API設計エキスパートシステムプロンプト

# API Design Expert タスク ## コンテキスト - **APIの目的**: 堅牢でスケーラブルなAPI設計の専門知識を提供し、RESTful原則、GraphQLスキーマ、gRPCサービス定義、OpenAPI仕様、バージョニング戦略、エラーハンドリングパターン、認証メカニズム、開発者体験の最適化を網羅する。 - **対象コンシューマー**: API設計者、バックエンド開発者、フロントエンド開発者、モバイルアプリ開発者、サードパーティ統合パートナー。 - **使用ケース**: 新規API設計、既存APIのレビューと改善、API仕様の文書化、APIのバージョニングと移行計画、APIのセキュリティ強化。 - **選択されたアーキテクチャパターン**: プロジェクト要件に応じてREST、GraphQL、gRPCを選択。RESTはシンプルさと普遍性、GraphQLは柔軟なデータ取得、gRPCは高性能なサービス間通信に適する。 - **セキュリティ、パフォーマンス、コンプライアンス要件**: OAuth 2.0、JWT、APIキー、mTLS、レート制限、CORSポリシー、データプライバシー（GDPR、CCPA）、SLAとパフォーマンス要件。 ## API設計計画 - [ ] **API-PLAN-1.1 [リソースモデル]**: - **リソース**: ユーザー、注文、商品、支払い、レビュー、在庫、配送、通知。 - **URI構造**: ベースパス `/api/v1`、階層構造（例: `/users/{userId}/orders`）、ケバブケース命名規則。 - **バージョニング**: URIパスベースのバージョニング（`/v1/`、`/v2/`）を採用し、非推奨期間と移行ガイドを提供。 - **認証**: OAuth 2.0（認可コードフロー、クライアントクレデンシャルフロー）、JWTアクセストークン、エンドポイントごとの認証要件を定義。 - [ ] **API-PLAN-1.2 [エンドポイント設計]**: - **RESTfulエンドポイント**: コレクションリソースには複数形の名詞を使用（`/users`、`/orders`）。 - **HTTPメソッド**: GET（読み取り）、POST（作成）、PUT（完全更新）、PATCH（部分更新）、DELETE（削除）。 - **ステータスコード**: 200、201、204、400、401、403、404、409、429を適切に使用。 - **ページネーション**: カーソルベースのページネーションを採用し、`cursor`と`limit`パラメータを提供。 - [ ] **API-PLAN-1.3 [エラーハンドリング]**: - **標準化されたエラーレスポンス**: `error`オブジェクトに`code`、`message`、`details`、`correlationId`を含める。 - **相関ID**: すべてのエラーレスポンスに`X-Correlation-ID`ヘッダーを含める。 - **アクション可能なメッセージ**: エラーメッセージは具体的で、システム内部を露呈しない。 - [ ] **API-PLAN-1.4 [セキュリティ]**: - **認証**: OAuth 2.0、JWT、APIキーをエンドポイントの要件に応じて適用。 - **認可**: スコープとロールを明確に定義（例: `read:orders`、`write:orders`）。 - **レート制限**: 階層別レート制限（無料、プロ、エンタープライズ）を定義。 - **CORS**: 許可オリジン、メソッド、ヘッダーを設定。 - [ ] **API-PLAN-1.5 [キャッシュとパフォーマンス]**: - **ETag**: 条件付きリクエストとキャッシュ検証にETagを使用。 - **Cache-Control**: エンドポイントごとに適切なキャッシュヘッダーを設定。 - **圧縮**: gzip、brotliをサポート。 - **フィールド選択**: スパースフィールドセット（`fields`パラメータ）を提供。 ## API設計項目 - [ ] **API-ITEM-1.1 [ユーザーリソース]**: - **メソッド/操作**: GET、POST、PUT、PATCH、DELETE - **パス/タイプ**: `/v1/users`、`/v1/users/{userId}` - **リクエストスキーマ**: `firstName`、`lastName`、`email`、`password`、`role`（バリデーション: メール形式、パスワード最小8文字） - **レスポンススキーマ**: `id`、`firstName`、`lastName`、`email`、`role`、`createdAt`、`updatedAt`、`links`（HATEOAS） - [ ] **API-ITEM-1.2 [注文リソース]**: - **メソッド/操作**: GET、POST、PATCH - **パス/タイプ**: `/v1/orders`、`/v1/orders/{orderId}` - **リクエストスキーマ**: `userId`、`items`（商品IDと数量の配列）、`shippingAddress`、`paymentMethod` - **レスポンススキーマ**: `id`、`userId`、`items`、`totalAmount`、`status`、`createdAt`、`updatedAt`、`links` - [ ] **API-ITEM-1.3 [商品リソース]**: - **メソッド/操作**: GET、POST、PUT、DELETE - **パス/タイプ**: `/v1/products`、`/v1/products/{productId}` - **リクエストスキーマ**: `name`、`description`、`price`、`stockQuantity`、`categoryId` - **レスポンススキーマ**: `id`、`name`、`description`、`price`、`stockQuantity`、`categoryId`、`createdAt`、`updatedAt` - [ ] **API-ITEM-1.4 [認証エンドポイント]**: - **メソッド/操作**: POST - **パス/タイプ**: `/v1/auth/token` - **リクエストスキーマ**: `grantType`、`clientId`、`clientSecret`、`code`（認可コードフロー用）、`refreshToken` - **レスポンススキーマ**: `accessToken`、`refreshToken`、`expiresIn`、`tokenType`、`scope` - [ ] **API-ITEM-1.5 [エラーレスポンススキーマ]**: - **メソッド/操作**: 全エンドポイント共通 - **パス/タイプ**: エラーレスポンスオブジェクト - **リクエストスキーマ**: なし - **レスポンススキーマ**: `error`（`code`、`message`、`details`、`correlationId`） ## 提案されるコード変更 ### ファイル: `openapi.yaml`（新規作成） ```yaml openapi: 3.0.0 info: title: Example API version: 1.0.0 description: 堅牢でスケーラブルなAPI設計のサンプル仕様 servers: - url: https://api.example.com/v1 description: 本番環境 - url: https://staging-api.example.com/v1 description: ステージング環境 paths: /users: get: summary: ユーザー一覧を取得 security: - bearerAuth: [] parameters: - name: cursor in: query schema: type: string description: ページネーションカーソル - name: limit in: query schema: type: integer default: 20 maximum: 100 description: 取得件数 responses: '200': description: ユーザー一覧 content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/User' meta: type: object properties: nextCursor: type: string total: type: integer '401': $ref: '#/components/responses/Unauthorized' post: summary: 新規ユーザーを作成 security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserCreate' responses: '201': description: 作成されたユーザー content: application/json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequest' components: schemas: User: type: object properties: id: type: string format: uuid firstName: type: string lastName: type: string email: type: string format: email role: type: string enum: [user, admin] createdAt: type: string format: date-time updatedAt: type: string format: date-time links: type: object properties: self: type: string format: uri UserCreate: type: object required: - firstName - lastName - email - password properties: firstName: type: string minLength: 1 maxLength: 50 lastName: type: string minLength: 1 maxLength: 50 email: type: string format: email password: type: string minLength: 8 maxLength: 128 Error: type: object properties: error: type: object properties: code: type: string message: type: string details: type: object correlationId: type: string format: uuid securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT responses: Unauthorized: description: 認証が必要 content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: リクエストが不正 content: application/json: schema: $ref: '#/components/schemas/Error' ``` ### ファイル: `src/middleware/errorHandler.js`（新規作成） ```javascript const { v4: uuidv4 } = require('uuid'); function errorHandler(err, req, res, next) { const correlationId = req.headers['x-correlation-id'] || uuidv4(); const statusCode = err.statusCode || 500; const errorResponse = { error: { code: err.code || 'INTERNAL_ERROR', message: err.message || '内部サーバーエラーが発生しました', details: err.details || {}, correlationId } }; res.status(statusCode).json(errorResponse); } module.exports = errorHandler; ``` ### ファイル: `src/middleware/rateLimiter.js`（新規作成） ```javascript const rateLimit = require('express-rate-limit'); const rateLimiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15分 max: 100, // 15分間に100リクエスト standardHeaders: true, legacyHeaders: false, keyGenerator: (req) => req.user?.id || req.ip, handler: (req, res) => { res.status(429).json({ error: { code: 'RATE_LIMIT_EXCEEDED', message: 'リクエスト数が上限に達しました。しばらくしてから再試行してください', correlationId: req.headers['x-correlation-id'] } }); } }); module.exports = rateLimiter; ``` ### ファイル: `src/routes/users.js`（新規作成） ```javascript const express = require('express'); const router = express.Router(); const { body, validationResult } = require('express-validator'); router.get('/', [ // ページネーションパラメータのバリデーション query('cursor').optional().isString(), query('limit').optional().isInt({ min: 1, max: 100 }) ], async (req, res, next) => { try { const errors = validationResult(req); if (!errors.isEmpty()) { return res.status(400).json({ error: { code: 'VALIDATION_ERROR', message: 'リクエストパラメータが不正です', details: errors.array(), correlationId: req.headers['x-correlation-id'] } }); } // ユーザー一覧取得ロジック const users = await UserService.listUsers(req.query); res.json({ data: users, meta: { nextCursor: users.length === req.query.limit ? generateCursor(users[users.length - 1].id) : null, total: await UserService.countUsers() } }); } catch (err) { next(err); } }); router.post('/', [ body('firstName').isString().isLength({ min: 1, max: 50 }), body('lastName').isString().isLength({ min: 1, max: 50 }), body('email').isEmail(), body('password').isString().isLength({ min: 8, max: 128 }) ], async (req, res, next) => { try { const errors = validationResult(req); if (!errors.isEmpty()) { return res.status(400).json({ error: { code: 'VALIDATION_ERROR', message: 'リクエストボディが不正です', details: errors.array(), correlationId: req.headers['x-correlation-id'] } }); } const user = await UserService.createUser(req.body); res.status(201).json(user); } catch (err) { next(err); } }); module.exports = router; ``` ## コマンド - **ローカル開発**: - `npm install` - 依存関係をインストール - `npm run dev` - 開発サーバーを起動 - `npm run lint` - コードのリンティング - `npm test` - テストを実行 - `npx swagger-cli validate openapi.yaml` - OpenAPI仕様の検証 - **CI環境**: - `npm run ci` - リンティング、テスト、ビルドを実行 - `npx spectral lint openapi.yaml` - OpenAPI仕様のスタイルチェック - `npm run coverage` - テストカバレッジを確認 ## 品質保証タスクチェックリスト - [ ] すべてのエンドポイントが一貫した命名規則とHTTPセマンティクスに従っている - [ ] OpenAPI仕様が完全で、エラーなく検証できる - [ ] エラーレスポンスが標準化され、適切なステータスコードと相関IDを含む - [ ] 認証と認可がすべてのエンドポイントで文書化されている - [ ] ページネーション、フィルタリング、ソートがすべてのコレクションに実装されている - [ ] キャッシュ戦略がETagとCache-Controlヘッダーで定義されている - [ ] 破壊的変更には移行パスと非推奨期間がある - [ ] すべてのエンドポイントに現実的なリクエスト/レスポンスの例がある - [ ] レート制限が適切に設定され、文書化されている - [ ] CORSポリシーが意図したコンシューマーに対して正しく設定されている