バックエンドAPIデザインで学ぶべき10のトピック

概要¶

バックエンドエンジニアが API 設計で習得すべき 10 のトピックをリスト化。

詳細¶

0. REST API with Versioning¶

GET /api/v1/users/123
GET /api/v2/users/123   ← 破壊的変更は新バージョンで

1. Pagination（ページネーション）¶

# Offset-based（シンプルだが大規模では遅い）
GET /posts?page=3&limit=20

# Cursor-based（推奨：大量データでも安定）
GET /posts?after=cursor_abc&limit=20

cursor 方式は「ページ内の挿入・削除」による重複/スキップが起きない。

2. Filtering & Sorting¶

GET /products?status=active&category=electronics&sort=-created_at
#                                                      ↑ - は降順

3. Idempotent Endpoints（冪等性）¶

# PUT, DELETE は冪等（同じリクエストを何度送っても結果が変わらない）
PUT /users/123    → 何度呼んでも同じ状態になる ✓
POST /orders      → 呼ぶたびに新しい注文が作られる ✗

# 冪等な POST を作るには Idempotency-Key ヘッダを使う
POST /payments
Idempotency-Key: uuid-xxxx   ← 同じキーの2回目以降は前回の結果を返す

4. OpenAPI Spec（API ドキュメント）¶

YAML/JSON でエンドポイントを定義 → Swagger UI で自動ドキュメント生成・クライアントコード自動生成。

5. API Gateway¶

認証・レートリミット・ルーティングを集約する。AWS API Gateway, Kong, nginx など。

6. Rate Limiting per User¶

# レスポンスヘッダで残量を通知
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699200000

# 超過時
HTTP/1.1 429 Too Many Requests
Retry-After: 60

7. Request Validation¶

入力値は必ずバリデーション。型チェック・必須フィールド・範囲チェックをビジネスロジックの手前で弾く。

8. Error Standardisation（エラーフォーマット統一）¶

{
  "status": 422,
  "code": "VALIDATION_ERROR",
  "message": "Email is required",
  "details": [
    { "field": "email", "message": "required" }
  ]
}

9. Metrics & Tracing¶

メトリクス: リクエスト数・エラーレート・P99 レスポンスタイム
トレーシング: trace_id をリクエスト全体で伝搬（OpenTelemetry）

なぜ重要か / いつ使うか¶

新しい API エンドポイントを設計するときの確認リストとして
コードレビューで API 品質を評価するとき
面接で「良い API 設計とは？」と聞かれたとき