Api design

API設計

目的

一貫性・拡張性・使いやすさを兼ね備えたAPIを、スキーマファーストで設計する。 OpenAPIで契約を先に固定し、サーバーとクライアントの並列実装を可能にする。

使うタイミング

• 新規サービスのエンドポイント定義を始めるとき
• 既存APIにフィールド追加・削除・型変更などの変更を加えるとき
• GraphQL/gRPCとRESTのどちらを採用するか判断するとき
• クライアントチームとの接続仕様を合意するとき

進め方

1. プロトコル選定: REST/GraphQL/gRPCの選択基準を確認し決定する
2. リソース洗い出し: ドメインオブジェクトを名詞(複数形)でリストアップする
3. エンドポイント一覧作成: メソッド・パス・認証要否・主なパラメータ・レスポンス概要を表にまとめる
4. エラー仕様策定: 使用するHTTPステータスとエラーレスポンス形式を全体で統一する
5. OpenAPI定義作成: エンドポイント一覧と仕様を.yamlで記述する(スキーマファースト)
6. モック生成: OpenAPIからモックサーバーを立ち上げ、クライアントチームに渡す
7. レビュー: チェックリストで一貫性・冪等性・後方互換性を確認する
8. 実装委譲: スキーマが固定したらサーバー実装とクライアント実装を並列エージェントに委譲する

設計の要点

プロトコル選定

プロトコル	採用場面
REST	デフォルト。外部公開API・シンプルなCRUD・迷ったらこれ
GraphQL	クライアント多様(Web/モバイル)・取得形状が多様・アンダーフェッチ/オーバーフェッチが問題になるとき
gRPC	内部サービス間通信・低レイテンシ・型安全なストリーミングが必要なとき

リソース指向設計

• URLは名詞(複数形): /users, /orders, /products
• 操作はHTTPメソッドで表現: GET(取得) / POST(作成) / PUT(全更新) / PATCH(部分更新) / DELETE(削除)
• ネストは1階層まで: /users/{id}/orders はOK、/users/{id}/orders/{oid}/items/{iid} は避ける
• 深いネストはフラット化: /order-items?order_id={oid} など

一貫性の確保

• 命名はプロジェクト全体で統一: snake_caseかcamelCaseかを決めて全エンドポイントで守る
• ページネーション方式を統一: offsetベース(?offset=0&limit=20)またはカーソルベース(?cursor=xxx&limit=20)のどちらかに統一
• フィルタ・ソート規約を統一: ?filter[status]=active, ?sort=-created_at のような形式を決める

レスポンス設計

• エンベロープを一貫させる: 単件は{"data": {...}}、一覧は{"data": [...], "meta": {"total": 100}}
• 日時: ISO 8601 UTC形式 (2025-01-15T09:00:00Z)
• 金額: 文字列("1980")または最小単位の整数(1980円→1980)で扱い、浮動小数点を避ける

HTTPステータスの正しい使用

コード	意味
200	成功(GETなど)
201	作成成功(POST)
204	成功・レスポンスボディなし(DELETE等)
400	リクエスト不正(バリデーションエラー等)
401	未認証(トークンなし・期限切れ)
403	権限なし(認証済みだがアクセス不可)
404	リソースが存在しない
409	競合(重複登録等)
422	意味的に処理不可(バリデーション詳細)
429	レート制限超過
500	サーバー内部エラー

冪等性

• PUT/DELETE は常に冪等に設計する
• 決済・注文など副作用のあるPOSTは Idempotency-Key ヘッダを受け付ける
• 同一キーでの再送には同一レスポンスを返す

バージョニングと後方互換

• URLプレフィックス方式を推奨: /v1/, /v2/
• 互換を壊さない変更(フィールド追加・任意パラメータ追加)→バージョン不要
• 破壊的変更(フィールド削除・型変更・必須化)→新バージョン作成+最低6ヶ月の移行期間を設ける

認証・レート制限

• Authorization: Bearer <token> またはAPIキーをヘッダで受け取る
• レート制限超過時: 429 Too Many Requests + Retry-After: 60 ヘッダを返す
• 詳細は [[security]] と連携する

成果物テンプレート

エンドポイント一覧

メソッド	パス	概要	認証	主なパラメータ	レスポンス
GET	/v1/users	ユーザー一覧取得	要	offset, limit, sort	200
POST	/v1/users	ユーザー作成	要	body: name, email	201
GET	/v1/users/{id}	ユーザー詳細取得	要	-	200 / 404
PATCH	/v1/users/{id}	ユーザー部分更新	要	body: (変更フィールド)	200 / 404
DELETE	/v1/users/{id}	ユーザー削除	要	-	204 / 404
GET	/v1/users/{id}/orders	注文一覧	要	cursor, limit	200

エラーレスポンス形式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "リクエストの内容が正しくありません。",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "メールアドレスの形式が正しくありません。"
      },
      {
        "field": "name",
        "code": "REQUIRED",
        "message": "名前は必須です。"
      }
    ]
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "指定されたリソースが見つかりません。",
    "details": []
  }
}

ページネーションレスポンス形式

{
  "data": [...],
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

チェックリスト

• URLに動詞が含まれていない
• リソース名が複数形の名詞になっている
• ネストが1階層以内に収まっている
• 命名規則(snake_case/camelCase)が全体で統一されている
• ページネーション方式が全一覧エンドポイントで統一されている
• エラーレスポンス形式が全エンドポイントで統一されている
• 400系と500系のステータスが正しく使い分けられている
• バリデーションエラーがフィールド単位で返せる
• PUT/DELETEが冪等に設計されている
• 副作用のあるPOSTにIdempotency-Key対応が検討されている
• 日時がISO 8601(UTC)になっている
• 破壊的変更がある場合にバージョンが上がっている
• OpenAPI定義ファイルが存在する
• 認証方式とレート制限の仕様が明記されている

アンチパターン

• 動詞だらけのURL: /getUser, /createOrder, /doPayment → 操作はHTTPメソッドで表現する
• すべて200でエラー表現: レスポンスボディ内のsuccess: falseフラグでエラーを返す → HTTPステータスを正しく使う
• 破壊的変更の無告知投入: 本番中のAPIからフィールドを削除・型変更する → バージョニングと移行期間を設ける
• エンドポイントごとに違うレスポンス形式: あるエンドポイントは{result: ...}、別は{data: ...} → エンベロープを統一する
• ページネーションなしで全件返す: 件数が増えるとタイムアウト・メモリ枯渇の原因になる
• 深すぎるネスト: /a/{id}/b/{id}/c/{id} → フラット化またはクエリパラメータで表現する
• 浮動小数点で金額を扱う: "amount": 19.80 → 文字列か最小単位整数にする

モデル委譲ガイド

共通原則は [[orchestration]] を参照。 スキーマファーストでOpenAPI定義を先に固定すると、API実装(サーバー)とクライアント実装(SDKや型定義)を並列エージェントに委譲できる。

役割	担当
司令塔(メインモデル)	リソース設計の意思決定、エンドポイント一覧作成、OpenAPI定義のレビューと承認、並列実装の調整
Opus相当	複雑なドメインのリソースモデリング、破壊的変更の影響範囲分析、セキュリティ設計の検討
Sonnet相当	OpenAPIファイルの記述、エラー仕様の具体化、型定義・モッククライアント生成
Haiku相当	ステータスコードの確認、命名規則の表記ゆれチェック、チェックリストの検証

関連スキル

• [[orchestration]] — インターフェース先行固定と並列エージェント委譲の共通原則
• [[requirements-definition]] — APIが満たすべき機能要件の整理
• [[architecture-design]] — REST/GraphQL/gRPC選択の上位判断
• [[database-design]] — リソース設計とデータモデルの整合
• [[security]] — 認証・認可・レート制限の詳細設計
• [[implementation]] — OpenAPI定義からのサーバー実装
• [[testing]] — APIテスト・契約テストの設計
• [[documentation]] — APIリファレンスドキュメントの整備