API 버전 관리와 서비스 간 하위 호환성을 어떻게 유지하나요?

Question

Accepted Answer

서비스가 독립적으로 배포되므로, 호출자가 발맞춰 업그레이드한다고 절대 가정할 수 없습니다. **API 버전 관리**와 **하위 호환성**은 생산자가 기존 소비자를 깨뜨리지 않고 진화할 수 있게 해줍니다.

## 버전 관리 전략

| 전략 | 예시 |
|---|---|
| URI 경로 | `GET /v2/orders/42` |
| 헤더 | `Accept: application/vnd.api.v2+json` |
| 스키마 진화 | 필드 추가, 절대 제거/이름 변경 금지 |

## 가산적(비파괴적) 변경을 선호

```text
비파괴적(안전):
  ✓ 새 선택적 필드 추가
  ✓ 새 엔드포인트 추가
  ✓ 새 enum 값 추가(클라이언트가 미지의 값을 허용한다면)

파괴적(새 버전 필요):
  ✗ 필드 제거 또는 이름 변경
  ✗ 타입 변경 또는 필드를 필수로 만들기
  ✗ 기존 필드의 의미 변경
```

## Protobuf는 이에 친화적

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // 새 필드 3 — 기존 클라이언트는 안전하게 무시
}
```

이름이 아니라 필드 번호가 와이어 형식을 정의하므로, 필드 추가는 하위 호환됩니다.

## 라이프사이클

```text
v2 출시 ─▶ v1 + v2 동시 운영 ─▶ 소비자 마이그레이션 ─▶ v1 폐기 예고 ─▶ v1 제거
```

## 함정

실제 트래픽이 아직 사용 중인 버전을 절대 제거하지 마세요. 폐기 전에 사용량을 추적하세요.

## 왜 중요한가

독립적 배포 가능성은 생산자가 모든 소비자의 릴리스를 조율하지 않고도 변경을 출시할 수 있을 때에만 작동합니다.

가산적 변경을 위해 설계하고 마이그레이션 동안 구버전을 지원하는 것이, 취약한 일괄(big-bang) 업그레이드를 강요하는 대신 그 독립성을 보존하는 길입니다.

URI 경로	`GET /v2/orders/42`
헤더	`Accept: application/vnd.api.v2+json`
스키마 진화	필드 추가, 절대 제거/이름 변경 금지