第 3 章

APIバージョン管理とセキュリティ

APIを一般に公開し、長期間運用するにあたっては、破壊的変更からクライアントを守る「バージョン管理」と、不正アクセスを防ぐ「セキュリティ対策」の設計が欠かせません。本章では、これらの設計パターンについて解説します。

1. APIのバージョン管理

APIのデータ構造や仕様を変更する際、既存のクライアントが動作しなくなる「破壊的変更」が発生する場合があります。これを避けるため、複数のバージョンを並行して稼働させる仕組みが必要です。

最も一般的で分かりやすい手法です。URIの先頭付近に /v1 などの識別子を埋め込みます。

GET https://api.example.com/v1/users

リクエストのパラメータとしてバージョンを渡します。

GET https://api.example.com/users?version=1

Accept ヘッダー（あるいはカスタムヘッダー）を使って、要求するバージョンを伝えます。

GET /users
Accept: application/vnd.example.v1+json

認証されていないクライアントからのアクセスを防ぎ、誰がリクエストを送信しているのかを特定するための仕組みです。

Rendering diagram...

APIキー (API Key): サービス登録時に各クライアントに発行される静的な文字列です。主に一般公開されているデータの取得（天気情報、地図情報など）で使われ、ヘッダー（X-API-Key など）に入れて送信します。
トークン認証 (JWT - JSON Web Token): ユーザーがID/パスワードでログインした後、サーバーが署名付きの暗号化トークン（JWT）を発行します。クライアントはこれ以降のリクエストヘッダーに以下のように含めます。
```
Authorization: Bearer <JWT_TOKEN>
```
サーバー側はセッションデータベースに問い合わせることなく、トークンの署名を検証するだけでユーザーを識別できるため、スケーラビリティに優れています。
OAuth 2.0 / OIDC (OpenID Connect): サードパーティアプリに対して、ユーザーのパスワードを開示することなくアクセス権限を与える（認可）ための業界標準プロトコルです。

レート制限 (Rate Limiting): DoS攻撃やAPIの過剰な呼び出しを防ぐため、IPアドレスやトークン単位で「1分あたり100回まで」といった制限を設けます。制限を超えた場合は 429 Too Many Requests を返します。
入力の厳格なバリデーション: SQLインジェクションやOSコマンドインジェクションなどを防ぐため、すべてのリクエストボディやクエリパラメータをサーバー側で厳格に検証します。