서비스가 독립적으로 배포되므로, 호출자가 발맞춰 업그레이드한다고 절대 가정할 수 없습니다. API 버전 관리와 하위 호환성은 생산자가 기존 소비자를 깨뜨리지 않고 진화할 수 있게 해줍니다.
서비스가 독립적으로 배포되므로, 호출자가 발맞춰 업그레이드한다고 절대 가정할 수 없습니다. API 버전 관리와 하위 호환성은 생산자가 기존 소비자를 깨뜨리지 않고 진화할 수 있게 해줍니다.
| 전략 | 예시 |
|---|
| URI 경로 | GET /v2/orders/42 |
| 헤더 | Accept: application/vnd.api.v2+json |
| 스키마 진화 | 필드 추가, 절대 제거/이름 변경 금지 |
비파괴적(안전):
✓ 새 선택적 필드 추가
✓ 새 엔드포인트 추가
✓ 새 enum 값 추가(클라이언트가 미지의 값을 허용한다면)
파괴적(새 버전 필요):
✗ 필드 제거 또는 이름 변경
✗ 타입 변경 또는 필드를 필수로 만들기
✗ 기존 필드의 의미 변경
message Order {
string id = 1;
double total = 2;
string currency = 3; // 새 필드 3 — 기존 클라이언트는 안전하게 무시
}
이름이 아니라 필드 번호가 와이어 형식을 정의하므로, 필드 추가는 하위 호환됩니다.
v2 출시 ─▶ v1 + v2 동시 운영 ─▶ 소비자 마이그레이션 ─▶ v1 폐기 예고 ─▶ v1 제거
실제 트래픽이 아직 사용 중인 버전을 절대 제거하지 마세요. 폐기 전에 사용량을 추적하세요.
독립적 배포 가능성은 생산자가 모든 소비자의 릴리스를 조율하지 않고도 변경을 출시할 수 있을 때에만 작동합니다.
가산적 변경을 위해 설계하고 마이그레이션 동안 구버전을 지원하는 것이, 취약한 일괄(big-bang) 업그레이드를 강요하는 대신 그 독립성을 보존하는 길입니다.