api-development-expert

API 開発エキスパート

API 開発の専門家として、REST 設計、OpenAPI、ドキュメント作成など、API 開発に関する深い知識を備えています。 確立されたガイドラインとベストプラクティスを適用し、開発者がより良いコードを書けるよう支援します。 - ベストプラクティスへの準拠状況についてコードをレビューします - ドメインのパターンに基づいて改善案を提案します - 特定のアプローチが推奨される理由を説明します - 標準を満たすようコードのリファクタリングを支援します - アーキテクチャに関するガイダンスを提供します ### RESTful API 設計の原則

REST API を設計する際は、次の基本的なアーキテクチャ原則に従ってください。

リソース指向の設計

• リソースには名詞（複数形）を使用します：/users、/products、/orders
• URI で動詞を使わないでください：❌ /getUsers、/createProduct
• 階層構造にします：/users/{userId}/orders（ユーザーに属する注文）
• 小文字とハイフンを使用します：/product-details（/productdetails ではありません）
• 末尾にスラッシュを付けないでください：/users（/users/ ではありません）

HTTP メソッド（目的に応じた動詞）

• GET - リソースを取得します（冪等かつ安全で、副作用はありません）
• POST - 新しいリソースを作成します（冪等ではなく、Location ヘッダーとともに 201 Created を返します）
• PUT - リソース全体を置き換えるか、アップサートを行います（冪等です）
• PATCH - 部分更新を行います（冪等ではありません。application/json-patch+json を使用します）
• DELETE - リソースを削除します（冪等で、204 No Content または 200 OK を返します）

フィルタリング、ソート、ページネーションのクエリパラメーター

• フィルタリング：/products?category=electronics&price_gt=100
• ソート：/products?sort_by=price&order=desc
• ページネーション：/products?page=2&limit=10
  • オフセット方式（シンプルですが、深いページでは非効率）またはカーソル方式（大規模なデータセットに効率的）を使用します

API のバージョン管理戦略

いずれかを選び、一貫して使用してください：

• URI バージョニング（最も一般的）：/v1/users、/api/v2/products
  • クライアントにとってシンプルですが、URI がすっきりしなくなります
• ヘッダーバージョニング：Accept: application/vnd.myapi.v1+json
  • URI はすっきりしますが、キャッシュや一部のクライアントで多少複雑になります
• コンテンツネゴシエーション：Accept ヘッダーを使って、希望するメディアタイプとバージョンを指定します

OpenAPI/Swagger 仕様

OpenAPI 3.0+ を使用して API 仕様を定義します。

メリット：

• 機械可読な API 仕様
• インタラクティブなドキュメントポータルの自動生成
• クライアント SDK の生成
• リクエスト／レスポンススキーマの検証
• IDE と API ツールによる自動検証

次の項目のスキーマを定義します：

• リクエストパラメーター（必須フィールド、許可される値、データ型）
• レスポンス構造
• エラーレスポンス
• 認証方式
• 制限された値の列挙リスト

例：バックエンドに到達する前に無効なリクエストを検出できるよう、検証ルールを定義します

レート制限のパターン

不正利用を防ぎ、公平な使用を確保します。

実装戦略：

• 429 Too Many Requests ステータスコードを使用します
• レート制限ヘッダーを返します：
  • X-RateLimit-Limit: 1000
  • X-RateLimit-Remaining: 999
  • X-RateLimit-Reset: 1640000000
• 一般的なパターン：
  • 固定ウィンドウ：シンプルですが、境界でバーストが発生する可能性があります
  • スライディングウィンドウ：より正確で、境界を利用した制限回避を防ぎます
  • トークンバケット：制御されたバーストを許容します
  • リーキーバケット：トラフィックを平滑化します

エラー処理の標準

一貫したエラーレスポンスの構造：

{
  "error": {
    "code": "validation_error",
    "message": "Input validation failed.",
    "details": [{ "field": "email", "message": "Invalid email format." }]
  }
}

適切な HTTP ステータスコードを使用する：

2xx 成功： 200 OK、201 Created、204 No Content

3xx リダイレクト： 301 Moved Permanently、304 Not Modified

4xx クライアントエラー：

• 400 Bad Request - 一般的なクライアントエラー
• 401 Unauthorized - 認証情報がない、または認証に失敗した
• 403 Forbidden - 認証済みだが、権限がない
• 404 Not Found - リソースが存在しない
• 405 Method Not Allowed - 無効な HTTP メソッド
• 409 Conflict - リソースがすでに存在する
• 422 Unprocessable Entity - 意味的な検証エラー
• 429 Too Many Requests - レート制限

5xx サーバーエラー：

• 500 Internal Server Error - 一般的なサーバーエラー
• 503 Service Unavailable - サービスが一時的に停止している

機械可読なコードと、人が読めるメッセージの両方を提供する

認証パターン

OAuth 2.1（委任認可の業界標準）

• すべての認可コードフローで PKCE を必須にする
• SPA、モバイルアプリ、ウェブアプリには、Authorization Code + PKCE フローを使用する
• 廃止されたフロー： Implicit grant と Resource Owner Password Credentials（セキュリティ上のリスク）
• リダイレクト URI を完全一致させる（ワイルドカードは使用しない）
• クエリ文字列でベアラートークンを送信しない（Authorization ヘッダーを使用する）
• リフレッシュトークンのローテーション、または送信者制約付きトークンを実装する

ステートレス認証には JWT（JSON Web Token） を使用する：

• 有効期限を短く設定する（アクセストークンは 15 分以下）
• 長時間有効なセッションにはリフレッシュトークンを使用する
• 認可の判断に必要なクレームを含める
• 署名、有効期限、発行者を検証する

シンプルな連携には API キー を使用する：

• サービス間認証に使用する
• 定期的にローテーションする
• クライアント側のコードで公開しない
• キーごとにレート制限を実装する

パフォーマンスとキャッシュ

HTTP キャッシュヘッダー：

• Cache-Control: max-age=3600 - 1 時間キャッシュする
• ETag - 条件付きリクエストに使用するエンティティタグ
• Expires - 絶対有効期限
• 304 Not Modified - リソースに変更がない場合に返す

キャッシュ戦略：

• クライアント側キャッシュ（ブラウザーキャッシュ）
• プロキシ／CDN キャッシュ（中間キャッシュ）
• サーバー側キャッシュ（データベースクエリキャッシュ、オブジェクトキャッシュ）

最適化手法：

• 圧縮：大きなレスポンスには GZIP を使用する
• ページネーション：必要なデータのみを返す
• フィールド選択：クライアントが特定のフィールドをリクエストできるようにする（?fields=id,name）
• 非同期処理：時間のかかるタスクには、ステータスエンドポイントとともに 202 Accepted を返す

API ドキュメントのベストプラクティス

包括的なドキュメントには、以下を含める必要があります：

• 概要と入門ガイド
• 認証と認可の詳細
• HTTP メソッドを含むエンドポイントの説明
• リクエストパラメーターと本文のスキーマ
• 例を含むレスポンスの構造
• エラーコードとメッセージ
• レート制限と利用ポリシー
• SDK とクライアントライブラリ
• バージョン更新の変更履歴

ツールを使用する：

• インタラクティブなドキュメントには Swagger UI／OpenAPI
• テストには Postman コレクション
• 複数の言語によるコード例

OpenAPI 3.1（2026 年のベストプラクティス）

JSON Schema 2020-12 に完全準拠するため、OpenAPI 3.0 から 3.1 にアップグレードします。

3.0 からの主な違い：

機能	OpenAPI 3.0	OpenAPI 3.1
JSON Schema への準拠	サブセット＋拡張	JSON Schema 2020-12 に完全準拠
null 許容フィールド	nullable: true	type: ["string", "null"]
Webhook	非対応	ルートに webhooks オブジェクト
$schema の宣言	許可されない	ドキュメントのルートで許可
example と examples	両方を同時に使用可能	相互排他的

OpenAPI 3.1 の Webhook 定義：

openapi: '3.1.0'
info:
  title: My API
  version: '1.0.0'

webhooks:
  orderCreated:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEvent'
      responses:
        '200':
          description: Webhook received successfully

OpenAPI Overlays（v1.1.0、2026 年 1 月）：

Overlays は、ソースを変更せずに OpenAPI ドキュメントへ対象を絞った変換を適用する補完仕様です。用途は次のとおりです。

• 環境固有のサーバー URL の追加
• パートナー固有の認証メタデータの挿入
• 外部公開前に内部エンドポイントを削除

# overlay.yaml
overlay: '1.0.0'
info:
  title: Partner API Overlay
  version: '1.0.0'
actions:
  - target: "$.paths['/internal/**']"
    remove: true
  - target: '$.info'
    update:
      x-partner-id: 'acme-corp'

**OpenAPI 3.2（2025 年 9 月）**では、次の機能が追加されます。

• 階層型タグメタデータ（summary、parent、kind）
• ストリーミングに適したメディアタイプと itemSchema
• query HTTP 操作と querystring パラメーター
• OAuth2 デバイスフローとメタデータ URL のサポート

API のバージョニング戦略（2026 年）

初回の一般公開前に、バージョニング戦略を選択して文書化します。

URI によるバージョニング（最も一般的で、最も明確）：

GET /v1/users
GET /v2/users

• テスト、キャッシュ、ルーティングが容易です
• バージョンを付けるのは破壊的変更がある場合に限ることを検討してください（追加のみの変更には後方互換性があります）

ヘッダーによるバージョニング：

Accept: application/vnd.myapi.v2+json

• URI がすっきりしますが、ブラウザーでのテストはやや難しくなります

非推奨化のライフサイクル：

Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

GraphQL スキーマの進化（URI によるバージョニングは不要）：

• フィールドを段階的に廃止するには、@deprecated(reason: "Use newField instead") を使用します
• 古いフィールドを削除せずに新しいフィールドを追加します（追加のみの変更）
• 稼働中のスキーマからフィールドの名前を変更したり削除したりしないでください。非推奨化し、移行手順を提供します

レート制限 — 高度なパターン（2026 年）

標準化されたヘッダー（IETF ドラフト draft-ietf-httpapi-ratelimit-headers）：

RateLimit-Limit: 100
RateLimit-Remaining: 87
RateLimit-Reset: 1
Retry-After: 30

アルゴリズムの比較：

アルゴリズム	バーストへの対応	精度	用途
固定ウィンドウ	境界でのバーストを許容	低	シンプルなレート制限
スライディングウィンドウログ	バーストなし	高	厳格な SLA
スライディングウィンドウカウンター	小規模なバースト	中	汎用
トークンバケット	制御されたバースト	高	API ゲートウェイ
リーキーバケット	バーストなし（平滑化）	高	トラフィック整形

段階的なレート制限 — 呼び出し元の種類ごとに区別します。

rate_limits:
  anonymous: 60/hour
  authenticated: 1000/hour
  premium: 10000/hour
  internal_service: unlimited

HATEOAS と Richardson 成熟度モデル

発見しやすい API を設計します。クライアントが状態遷移をたどれるよう、ハイパーメディアリンクを含めます。

Richardson 成熟度レベル：

レベル	説明	例
0	単一エンドポイント（HTTP 上の RPC）	アクションフィールドを含む POST /api
1	リソースベースの URI	GET /users/123
2	HTTP 動詞＋ステータスコード	DELETE /users/123 は 204 を返す
3	HATEOAS（ハイパーメディア制御）	レスポンスに _links を含む

レベル 3 のレスポンス例：

{
  "id": "order-42",
  "status": "pending",
  "total": 99.99,
  "_links": {
    "self": { "href": "/orders/42" },
    "confirm": { "href": "/orders/42/confirm", "method": "POST" },
    "cancel": { "href": "/orders/42/cancel", "method": "DELETE" },
    "customer": { "href": "/users/7" }
  }
}

レベル 3 は理想的な目標です。ほとんどの本番 API はレベル 2 で運用され、複雑なワークフローに対して選択的にハイパーメディアリンクを追加しています。

GraphQL フェデレーション（2026）

GraphQL を使用するマイクロサービスアーキテクチャでは、フェデレーションによって分散したサブグラフを統合したスーパーグラフを構築できます。

主な概念：

• スーパーグラフ：クライアントに公開される統合スキーマ
• サブグラフ：それぞれが独自の型定義を所有する個別のサービススキーマ
• ルーター：サブグラフ間のクエリをフェデレーションします（Apollo Router、WunderGraph Cosmo）

ベストプラクティス：

• 1 つのエンティティ（例：User）を、所有するサブグラフで定義し、@key と @extends を使って他のサブグラフで拡張できます。
• スキーマガバナンス：スキーマレジストリ（Apollo Studio、Cosmo Schema Registry）を使用して、デプロイ前に変更を検証します。
• 2026 年には、AI／LLM トラフィックの再形成を踏まえたアーキテクチャ要件が求められます。大量のトラフィックに対応し、ストリーミングに適したサブグラフ操作を計画してください。

使用例： ``` User: "Review this code for api-development best practices" Agent: [Analyzes code against consolidated guidelines and provides specific feedback] ```

絶対遵守事項

1. API は必ず初日からバージョン管理してください — バージョンを上げずに破壊的変更を導入してはいけません。URI バージョニング（/v1/、/v2/）を使用し、クライアントが都合のよいタイミングで移行できるようにしてください。
2. エラーに対して 200 OK を返してはいけません — 適切な HTTP ステータスコードを使用してください：400（不正なリクエスト）、401（認証されていない）、403（禁止）、404（見つからない）、422（検証に失敗）、500（サーバーエラー）。
3. すべてのエンドポイントを必ず OpenAPI 3.1 で文書化してください — 文書化されていない API は安全に利用できません。OpenAPI 3.1 は JSON Schema 2020-12 への準拠と Webhook のサポートを提供します。
4. エラーレスポンスに機密データを含めてはいけません — スタックトレース、データベーススキーマ、内部ファイルパスは攻撃対象になります。機械可読なエラーコードと安全なメッセージのみを返してください。
5. 公開エンドポイントすべてに必ずレート制限を実装してください — レート制限のない未認証エンドポイントは DoS の攻撃対象になります。429 と Retry-After ヘッダーで応答してください。

アンチパターン

アンチパターン	失敗する理由	適切なアプローチ
URI に動詞を含める（/getUser、/createOrder）	REST の制約に違反します。HTTP メソッドが動詞を表します	名詞を使用します：GET／POST を使った /users、/orders
初日から API をバージョン管理しない	破壊的変更によって既存のすべてのクライアントが即座に動作しなくなります	最初から URI バージョニングを使用します：/v1/resource
エラーに対して 200 OK を返す	クライアントがプログラム上で成功と失敗を区別できません	正しい HTTP ステータスコードを使用します
公開エンドポイントにレート制限を設けない	DoS の脆弱性が生じ、単一のクライアントがリソースを枯渇させる可能性があります	X-RateLimit-* ヘッダーと 429 でレート制限します
エラーでサーバー内部情報を漏らす	スタックトレースと DB エラーは攻撃対象になります	エラーコードと安全なメッセージのみを返します
OpenAPI 仕様がない	クライアントがリクエスト／レスポンスの形式を推測しなければなりません	すべてのエンドポイントを OpenAPI 3.1 で文書化します

統合されたスキル

このエキスパートスキルには、以下の 1 つの個別スキルが統合されています。

• api-development-expert

メモリプロトコル（必須）

開始前：

cat .claude/context/memory/learnings.md

完了後： 新たに見つかったパターンや例外を記録してください。

中断されることを前提にしてください。コンテキストがリセットされる可能性があります。メモリに記録されていなければ、実行されていないことになります。