api-design-reviewer

API 設計レビュアー

ティア： POWERFUL
カテゴリー： エンジニアリング／アーキテクチャ
メンテナー： Claude Skills Team

概要

API 設計レビュアーのスキルは、REST の規約、ベストプラクティス、業界標準に焦点を当て、API 設計を包括的に分析・レビューします。このスキルは、自動リンティング、破壊的変更の検出、設計スコアカードを通じて、エンジニアリングチームが一貫性と保守性に優れた、適切に設計された API を構築できるよう支援します。

クイックスタート — まずツールを実行する

# 1. Lint an OpenAPI/Swagger spec for convention violations
python3 scripts/api_linter.py openapi.json --format json -o lint.json

# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking)
python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json

# 3. Score overall design quality (gate: --min-grade fails below threshold)
python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json

レビューの流れ：3 つすべてを実行し、リンターの指摘事項、破壊的変更、評価をユーザーに報告してから修正し、リンターの指摘がなくなり、--exit-on-breaking がパスするか（または破壊的変更に合わせてバージョンを上げ）、スコアカードが合意済みの --min-grade を満たすまで再実行します。文章だけで API レビューを承認してはいけません。必ずツールの出力を添付してください。

主な機能

1. API のリンティングと規約の分析

• リソースの命名規約：リソースには kebab-case、フィールドには camelCase を適用します
• HTTP メソッドの使用：GET、POST、PUT、PATCH、DELETE の適切な使用を検証します
• URL 構造：エンドポイントのパターンを分析し、一貫性と REST に沿った設計を確認します
• ステータスコードの準拠：適切な HTTP ステータスコードが使用されていることを確認します
• エラーレスポンスの形式：一貫したエラーレスポンス構造であることを検証します
• ドキュメントの網羅性：説明の不足やドキュメントの欠落を確認します

2. 破壊的変更の検出

• エンドポイントの削除：削除または非推奨になったエンドポイントを検出します
• レスポンス構造の変更：レスポンス構造の変更を特定します
• フィールドの削除：API レスポンス内で削除または名前が変更されたフィールドを追跡します
• 型の変更：クライアントに影響する可能性があるフィールド型の変更を検出します
• 必須フィールドの追加：既存の連携に影響する可能性がある新しい必須フィールドを警告します
• ステータスコードの変更：想定されるステータスコードの変更を検出します

3. API 設計のスコアリングと評価

• 一貫性の分析（30%）：命名規約、レスポンスのパターン、構造の一貫性を評価します
• ドキュメントの品質（20%）：API ドキュメントの完全性と明瞭さを評価します
• セキュリティの実装（20%）：認証、認可、セキュリティヘッダーをレビューします
• 使いやすさの設計（15%）：使いやすさ、発見しやすさ、開発者エクスペリエンスを分析します
• パフォーマンスのパターン（15%）：キャッシュ、ページネーション、効率性のパターンを評価します

REST 設計の原則

リソースの命名規約

✅ Good Examples:
- /api/v1/users
- /api/v1/user-profiles
- /api/v1/orders/123/line-items

❌ Bad Examples:
- /api/v1/getUsers
- /api/v1/user_profiles
- /api/v1/orders/123/lineItems

HTTP メソッドの使用

• GET：リソースを取得します（安全で、冪等です）
• POST：新しいリソースを作成します（冪等ではありません）
• PUT：リソース全体を置き換えます（冪等です）
• PATCH：リソースの一部を更新します（必ずしも冪等ではありません）
• DELETE：リソースを削除します（冪等です）

URL 構造のベストプラクティス

Collection Resources: /api/v1/users
Individual Resources: /api/v1/users/123
Nested Resources: /api/v1/users/123/orders
Actions: /api/v1/users/123/activate (POST)
Filtering: /api/v1/users?status=active&role=admin

バージョニング戦略

1. URL バージョニング（推奨）

/api/v1/users
/api/v2/users

メリット：明確で、明示的で、ルーティングが簡単です
デメリット：URL が増え、キャッシュが複雑になります

2. ヘッダーバージョニング

GET /api/users
Accept: application/vnd.api+json;version=1

メリット：URL がすっきりし、コンテンツネゴシエーションに対応します
デメリット：目立ちにくく、手動でのテストが難しくなります

3. メディアタイプバージョニング

GET /api/users
Accept: application/vnd.myapi.v1+json

メリット：REST に沿っており、複数の表現に対応します
デメリット：複雑で、実装が難しくなります

4. クエリパラメータバージョニング

/api/users?version=1

メリット：実装が簡単です
デメリット：REST に沿っておらず、無視される可能性があります

ページネーションのパターン

オフセットベースのページネーション

{
  "data": [...],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "total": 150,
    "hasMore": true
  }
}

カーソルベースのページネーション

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true
  }
}

ページベースのページネーション

{
  "data": [...],
  "pagination": {
    "page": 3,
    "pageSize": 10,
    "totalPages": 15,
    "totalItems": 150
  }
}

エラーレスポンスの形式

標準的なエラー構造

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email address is not valid"
      }
    ],
    "requestId": "req-123456",
    "timestamp": "2026-02-16T13:00:00Z"
  }
}

HTTP ステータスコードの使用

• 400 Bad Request：リクエストの構文またはパラメーターが無効です
• 401 Unauthorized：認証が必要です
• 403 Forbidden：アクセスが拒否されました（認証済みですが、認可されていません）
• 404 Not Found：リソースが見つかりません
• 409 Conflict：リソースが競合しています（重複、バージョンの不一致）
• 422 Unprocessable Entity：構文は有効ですが、意味上のエラーがあります
• 429 Too Many Requests：レート制限を超過しました
• 500 Internal Server Error：予期しないサーバーエラーです

認証と認可のパターン

ベアラートークン認証

Authorization: Bearer <token>

API キー認証

X-API-Key: <api-key>
Authorization: Api-Key <api-key>

OAuth 2.0 フロー

Authorization: Bearer <oauth-access-token>

ロールベースアクセス制御（RBAC）

{
  "user": {
    "id": "123",
    "roles": ["admin", "editor"],
    "permissions": ["read:users", "write:orders"]
  }
}

レート制限の実装

ヘッダー

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

制限超過時のレスポンス

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 3600
  }
}

HATEOAS（アプリケーション状態のエンジンとしてのハイパーメディア）

実装例

{
  "id": "123",
  "name": "John Doe",
  "email": "[email protected]",
  "_links": {
    "self": { "href": "/api/v1/users/123" },
    "orders": { "href": "/api/v1/users/123/orders" },
    "profile": { "href": "/api/v1/users/123/profile" },
    "deactivate": { 
      "href": "/api/v1/users/123/deactivate",
      "method": "POST"
    }
  }
}

冪等性

冪等なメソッド

• GET：常に安全で冪等です
• PUT：冪等である必要があります（リソース全体を置き換えます）
• DELETE：冪等である必要があります（同じ結果になります）
• PATCH：冪等な場合とそうでない場合があります

冪等性キー

POST /api/v1/payments
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

下位互換性のガイドライン

安全な変更（破壊的変更ではない）

• リクエストへの任意フィールドの追加
• レスポンスへのフィールドの追加
• 新しいエンドポイントの追加
• 必須フィールドを任意に変更
• 新しい列挙値の追加（適切に処理する場合）

破壊的変更（バージョンの更新が必要）

• レスポンスからのフィールドの削除
• 任意フィールドを必須に変更
• フィールドの型の変更
• エンドポイントの削除
• URL 構造の変更
• エラーレスポンス形式の変更

OpenAPI/Swagger の検証

必須コンポーネント

• API 情報：タイトル、説明、バージョン
• サーバー情報：ベース URL と説明
• パス定義：メソッドを含むすべてのエンドポイント
• パラメーター定義：クエリ、パス、ヘッダーのパラメーター
• リクエスト／レスポンスのスキーマ：完全なデータモデル
• セキュリティ定義：認証方式
• エラーレスポンス：標準的なエラー形式

ベストプラクティス

• 一貫性のある命名規則を使用する
• すべてのコンポーネントに詳細な説明を記載する
• 複雑なオブジェクトには例を含める
• 再利用可能なコンポーネントとスキーマを定義する
• OpenAPI 仕様に照らして検証する

パフォーマンスに関する考慮事項

キャッシュ戦略

Cache-Control: public, max-age=3600
ETag: "123456789"
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

効率的なデータ転送

• 適切な HTTP メソッドを使用する
• フィールド選択を実装する（?fields=id,name,email）
• 圧縮（gzip）をサポートする
• 効率的なページネーションを実装する
• 条件付きリクエストに ETag を使用する

リソースの最適化

• N+1 クエリを避ける
• バッチ処理を実装する
• 負荷の高い処理には非同期処理を使用する
• 部分更新（PATCH）をサポートする

セキュリティのベストプラクティス

入力検証

• すべての入力パラメーターを検証する
• ユーザーデータをサニタイズする
• パラメーター化クエリを使用する
• リクエストサイズの制限を実装する

認証セキュリティ

• すべての通信で HTTPS を使用する
• 安全なトークン保存を実装する
• トークンの有効期限と更新をサポートする
• 強力な認証方式を使用する

認可制御

• 最小権限の原則を実装する
• リソースベースの権限を使用する
• きめ細かなアクセス制御をサポートする
• アクセスパターンを監査する

ツールとスクリプト

api_linter.py

REST の規約とベストプラクティスへの準拠状況を確認するため、API 仕様を分析します。

機能：

• OpenAPI/Swagger 仕様の検証
• 命名規則のチェック
• HTTP メソッドの使用状況の検証
• エラー形式の一貫性チェック
• ドキュメントの完全性の分析

breaking_change_detector.py

API 仕様のバージョンを比較して、破壊的変更を特定します。

機能：

• エンドポイントの比較
• スキーマ変更の検出
• フィールドの削除／変更の追跡
• 移行ガイドの生成
• 影響の重大度の評価

api_scorecard.py

API 設計の品質を包括的に採点します。

機能：

• 多角的な採点
• 詳細な改善提案
• レターグレードによる評価（A-F）
• ベンチマークとの比較
• 進捗の追跡

統合例

CI/CD 統合

- name: "api-linting"
  run: python scripts/api_linter.py openapi.json

- name: "breaking-change-detection"
  run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json

- name: "api-scorecard"
  run: python scripts/api_scorecard.py openapi.json

プリコミットフック

#!/bin/bash
python engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
  echo "API linting failed. Please fix the issues before committing."
  exit 1
fi

ベストプラクティスのまとめ

1. 一貫性を最優先：一貫した命名、レスポンス形式、パターンを維持します
2. ドキュメント：包括的で最新の API ドキュメントを提供します
3. バージョン管理：明確なバージョン管理戦略を用意し、進化に備えます
4. エラー処理：一貫性のある、分かりやすいエラーレスポンスを実装します
5. セキュリティ：API のあらゆる層にセキュリティを組み込みます
6. パフォーマンス：最初から拡張性と効率性を考慮して設計します
7. 後方互換性：破壊的変更を最小限に抑え、移行手段を提供します
8. テスト：コントラクトテストを含む包括的なテストを実装します
9. 監視：API の使用状況とパフォーマンスを可観測にします
10. 開発者エクスペリエンス：使いやすさと分かりやすいドキュメントを優先します

避けるべきよくあるアンチパターン

1. 動詞ベースの URL：リソースにはアクションではなく名詞を使用します
2. 一貫性のないレスポンス形式：標準的なレスポンス構造を維持します
3. 過度なネスト：リソース階層を深くネストしないようにします
4. HTTP ステータスコードの無視：状況に応じた適切なステータスコードを使用します
5. 不適切なエラーメッセージ：対応につながる具体的なエラー情報を提供します
6. ページネーションの欠如：リストエンドポイントには必ずページネーションを実装します
7. バージョン管理戦略の欠如：初日から API の進化を計画します
8. 内部構造の露出：内部の利便性ではなく、外部からの利用を想定して API を設計します
9. レート制限の欠如：不正利用や過負荷から API を保護します
10. 不十分なテスト：エラーケースや境界条件を含むあらゆる側面をテストします

リンティング、破壊的変更の検出、スコアリングの各ツールを定期的に使用すると、継続的な改善につながり、開発ライフサイクル全体を通じて API の品質維持に役立ちます。