api-design-patterns

API 設計パターン

一貫性があり、開発者にとって使いやすい API を構築するための RESTful API 設計原則です。リソース設計、エラー処理、セキュリティ、ページネーション、バージョン管理、レスポンス形式、ドキュメントを網羅する 7 カテゴリー、38 個のルールが含まれています。

メタデータ

• バージョン： 2.0.0
• ルール数： 7 カテゴリーにわたる 38 個のルール
• ライセンス： MIT

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• 新しい API エンドポイントを設計するとき
• 既存の API 構造をレビューするとき
• エラー処理とバリデーションを実装するとき
• ページネーション、フィルタリング、ソートを設定するとき
• API のバージョン管理戦略を計画するとき
• API セキュリティ（認証、CORS、レート制限）を設定するとき
• API ドキュメント（OpenAPI/Swagger）を作成するとき

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	リソース設計	重大	rest-
2	エラー処理	重大	error-
3	セキュリティ	重大	sec-
4	ページネーションとフィルタリング	高	page-、filter-、sort-
5	バージョン管理	高	ver-
6	レスポンス形式	中	resp-
7	ドキュメント	中	doc-

クイックリファレンス

1. リソース設計（重大）

• rest-nouns-not-verbs - エンドポイントには動詞ではなく名詞を使用する
• rest-plural-resources - リソース名には複数形を使用する
• rest-http-methods - HTTP メソッド（GET、POST、PUT、PATCH、DELETE）を正しく使用する
• rest-nested-resources - リソースを適切にネストする（最大 2 階層）
• rest-status-codes - 適切な HTTP ステータスコードを使用する
• rest-idempotency - 冪等性キーを使用した冪等な操作
• rest-hateoas - 発見可能性を高めるハイパーメディアリンク
• rest-resource-actions - CRUD 以外のアクションをサブリソースとして扱う

2. エラー処理（重大）

• error-consistent-format - 一貫性のあるエラーレスポンス構造
• error-meaningful-messages - 役に立ち、対応につながるエラーメッセージ
• error-validation-details - フィールド単位のバリデーションエラー
• error-error-codes - 機械可読なエラーコード
• error-no-stack-traces - 本番環境でスタックトレースを絶対に公開しない
• error-request-id - デバッグ用にリクエスト ID を含める

3. セキュリティ（重大）

• sec-authentication - 適切な認証の実装（OAuth2/JWT）
• sec-authorization - リソースレベルの権限（RBAC）
• sec-rate-limiting - レート制限による不正利用の防止
• sec-input-validation - すべての入力を検証し、サニタイズする
• sec-cors-config - 許可リストを使用した CORS の設定
• sec-https-only - すべての通信で HTTPS を強制する
• sec-sensitive-data - パスワード、トークン、PII を保護する

4. ページネーションとフィルタリング（高）

• page-cursor-based - 大規模なデータセットにはカーソルページネーションを使用する
• page-offset-based - シンプルなケースにはオフセットページネーションを使用する
• page-consistent-params - 一貫性のあるパラメーター名を使用する
• page-metadata - レスポンスにページネーションのメタデータを含める
• filter-query-params - クエリパラメーターでフィルタリングする
• sort-flexible - 降順を示す - プレフィックスを使い、柔軟にソートする

5. バージョン管理（高）

• ver-url-path - URL パスでバージョンを指定する（/api/v1/）
• ver-header-based - Accept ヘッダーでバージョンを指定する
• ver-backward-compatible - 下位互換性を維持する
• ver-deprecation - Sunset ヘッダーを使った非推奨化戦略

6. レスポンス形式（中）

• resp-consistent-structure - 一貫性のあるレスポンスエンベロープ
• resp-json-conventions - JSON の命名規則
• resp-partial-responses - フィールドの選択（スパースフィールドセット）
• resp-compression - レスポンスの圧縮（gzip/Brotli）

7. ドキュメント（中）

• doc-openapi - OpenAPI/Swagger 仕様
• doc-examples - リクエストとレスポンスの例
• doc-changelog - API の変更履歴

基本ガイドライン

リソースの命名

# ❌ Verbs in URLs
GET    /getUsers
POST   /createUser

# ✅ Nouns with HTTP methods
GET    /users          # List users
POST   /users          # Create user
GET    /users/123      # Get user
PUT    /users/123      # Update user (full)
PATCH  /users/123      # Update user (partial)
DELETE /users/123      # Delete user

エラーレスポンス形式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Please provide a valid email address"
      }
    ],
    "request_id": "req_abc123"
  }
}

ページネーション

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total_pages": 10,
    "total_count": 195
  },
  "links": {
    "first": "/users?page=1&per_page=20",
    "prev": "/users?page=1&per_page=20",
    "next": "/users?page=3&per_page=20",
    "last": "/users?page=10&per_page=20"
  }
}

レート制限ヘッダー

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1640995200

使用方法

詳しい説明については、個々のルールファイルを参照してください。

rules/rest-http-methods.md
rules/error-consistent-format.md
rules/page-cursor-based.md
rules/sec-authentication.md
rules/ver-url-path.md
rules/doc-openapi.md

参考資料

• RESTful API ガイドライン
• Zalando RESTful API ガイドライン
• Microsoft API ガイドライン
• Google API 設計ガイド
• OpenAPI 仕様

完全版のコンパイル済みドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。