API をバージョン管理し、サービス間で後方互換性を保つにはどうしますか?

Question

Accepted Answer

サービスは独立してデプロイされるため、呼び出し元が同期してアップグレードされることを前提にすることはできません。**API versioning** と **backward compatibility** により、プロデューサーは既存のコンシューマーを破壊することなく進化できます。

## バージョニング戦略

| 戦略 | 例 |
|---|---|
| URIパス | `GET /v2/orders/42` |
| ヘッダ | `Accept: application/vnd.api.v2+json` |
| スキーマ進化 | フィールドを追加し、削除/名前変更しない |

## 加算的（破壊的でない）変更を優先する

```text
NON-BREAKING (safe):
  ✓ add a new optional field
  ✓ add a new endpoint
  ✓ add a new enum value (if clients tolerate unknowns)

BREAKING (needs a new version):
  ✗ remove or rename a field
  ✗ change a type or make a field required
  ✗ change semantics of an existing field
```

## Protobuf はこれに適している

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

フィールド番号は名前ではなくワイヤフォーマットを定義するため、フィールドの追加は後方互換性があります。

## ライフサイクル

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## 落とし穴

実際のトラフィックがまだ使用中のバージョンを削除しないでください。廃止する前に使用状況を追跡してください。

## なぜ重要なのか

独立したデプロイ可能性は、プロデューサーがすべてのコンシューマーのリリースを調整することなく変更をリリースできる場合にのみ機能します。

加算的な変更のための設計と移行中の古いバージョンのサポートは、脆い大規模な一括アップグレードを強制する代わりに、その独立性を保持するものです。

URIパス	`GET /v2/orders/42`
ヘッダ	`Accept: application/vnd.api.v2+json`
スキーマ進化	フィールドを追加し、削除/名前変更しない