主な API versioning 戦略は何で、version をどう deprecate しますか?

Question

IT Interview Practice · Accepted Answer

Versioning により、既存の client を壊さずに **破壊的変更 (breaking changes)** で API を進化させられます。主流の 3 つの戦略と、deprecation プロセスがあります。

## 3 つの戦略

**1. URI versioning** — version がパスにあります。
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
最も単純で最も可視的。ルーティング、キャッシュ、ブラウザでのテストが容易です。欠点: 技術的には「URI がリソースを識別する」に反します (同じ user が 2 つの URL を持つ)。これは圧倒的に最も一般的な選択です (GitHub、歴史的に Stripe)。

**2. Custom header versioning** — version がヘッダで運ばれます。
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
URL をきれいに保ちますが、ブラウザでは不可視でキャッシュが難しくなります。

**3. Media-type (content negotiation) versioning** — version が `Accept` にあります。
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
最も「RESTful」 (リソース URL が安定し、その表現だけが versioning される) ですが、消費者にとって最も取っつきにくいです。

## 何が破壊的か

```text
BREAKING      → field の削除/リネーム、型の変更、auth の変更、validation の厳格化
NON-BREAKING  → 新しい optional field の追加、新しい endpoint の追加、enum 値の追加*
```
新しい version が必要なのは破壊的変更だけ。非破壊的変更は現在のものに追加します。

## Deprecation プロセス

1. ドキュメントと changelog で日付付きで **告知** する。
2. client がプログラム的に気づけるよう、ヘッダで **実行時にシグナル** する:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. 旧 version の利用を **監視** し、残った呼び出し側に連絡する。
4. 利用がほぼゼロに落ちてからのみ **Sunset** する。

## なぜ重要なのか

面接官がこれを尋ねるのは、依存する client を壊さずに production で API を成長させられるか — 理論ではなく現実の運用上の懸念 — を見るためです。最強の答えは 2 つの区別をします: 第一に、**ほとんどの変更は非破壊的** で version bump を引き起こすべきではない (追加的変更は現在の version に入る) こと、versioning は真に破壊的な変更のために取っておくこと。第二に、*戦略* より *プロセス* が重要であること — `Deprecation`/`Sunset` ヘッダと利用監視を伴う明確な deprecation タイムラインこそが実際に消費者を守ります。URI versioning は可視性とツールサポートで実際には勝ちますが、トレードオフ (header と media-type は URL を安定に保ちより RESTful だが、発見可能性を犠牲にする) を知っていることは、単に `/v1/` を模倣するのでなく設計空間を理解していることを示します。

3 つの戦略

何が破壊的か

Deprecation プロセス

なぜ重要なのか

関連する質問