api-designer

API 設計

堅牢で、スケーラブルかつ保守しやすい REST および GraphQL API の設計に精通しています。

このスキルが有効になるタイミング

次の場合に有効になります。

• 新しい API を設計する
• API 設計をレビューする
• 既存の API を改善する
• API 仕様を作成する

REST API 設計の原則

1. リソース指向の設計

推奨：

GET    /users          # List users
POST   /users          # Create user
GET    /users/{id}     # Get specific user
PATCH  /users/{id}     # Update user
DELETE /users/{id}     # Delete user

避ける例：

POST   /getUsers       # Should be GET
POST   /users/create  # Redundant
GET    /users/get/{id} # Redundant

2. HTTP メソッド

メソッド	安全性	冪等性	用途
GET	✓	✓	リソースの読み取り
POST	✗	✗	リソースの作成
PUT	✗	✓	リソースの置き換え
PATCH	✗	✗	リソースの更新
DELETE	✗	✓	リソースの削除

3. ステータスコード

コード	意味	用途
200	OK	GET、PATCH、DELETE の成功
201	Created	POST の成功
204	No Content	ボディなしの DELETE の成功
400	Bad Request	無効な入力
401	Unauthorized	認証情報がない、または無効
403	Forbidden	認証済みだが、認可されていない
404	Not Found	リソースが存在しない
409	Conflict	リソースがすでに存在する
422	Unprocessable	構文は有効だが、意味上のエラーがある
429	Too Many Requests	レート制限を超過
500	Internal Server Error	サーバーエラー

4. 命名規則

• URL：kebab-case（/user-preferences）
• JSON：camelCase（{"userId": "123"}）
• クエリパラメーター：snake_case または camelCase（?page_size=10）

5. ページネーション

GET /users?page=1&page_size=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100,
    "total_pages": 5
  }
}

6. フィルタリングとソート

GET /users?status=active&sort=-created_at,name

# -created_at = descending
# name = ascending

GraphQL API 設計

スキーマ設計

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

type User {
  id: ID!
  email: String!
  profile: Profile
  posts(first: Int, after: String): PostConnection!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

ベストプラクティス

• Null 許容性：デフォルトでは非 null とし、適切な場合にのみ null を許容します
• コネクション：リストにはカーソルベースのページネーションを使用します
• ペイロード：一貫したエラー処理のためにミューテーションペイロードを使用します
• 説明：すべての型とフィールドを文書化します

API のバージョン管理

方法

URL バージョン管理（推奨）：

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

ヘッダーによるバージョン管理：

GET /users
Accept: application/vnd.myapi.v2+json

バージョン管理のガイドライン

• v1 から始めます
• 可能な限り後方互換性を維持します
• 旧バージョンは事前に通知して非推奨にします
• 互換性を破る変更を文書化します

認証と認可

認証方法

1. JWT ベアラートークン

Authorization: Bearer <token>

2. API キー

X-API-Key: <key>

3. OAuth 2.0

Authorization: Bearer <access_token>

認可

• ロール／権限を使用します
• エンドポイントごとに必要な権限を文書化します
• 認可に失敗した場合は 403 を返します

レート制限

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1631234567

推奨される制限：

• パブリック API：100〜1000 リクエスト／時間
• 認証済み API：1000〜10000 リクエスト／時間
• Webhook：10〜100 リクエスト／分

ドキュメントの要件

• すべてのエンドポイントを文書化する
• リクエスト／レスポンスの例
• 認証要件
• エラーレスポンスの形式
• レート制限
• SDK の例（利用可能な場合）

スクリプト

API のひな形を生成：

python3 scripts/generate_api.py --name <resource-name> --output api-design.md

API 設計を検証：

python3 scripts/validate_api.py --input api-design.md

参考資料

• references/rest-patterns.md - REST 設計パターン
• references/graphql-patterns.md - GraphQL 設計パターン
• REST API チュートリアル
• GraphQL のベストプラクティス