중대한 대규모 변경

경우에 따라서는 매우 중요한, 기존 버전과 호환이 안 되는 변경을 API에 적용해야 할 때가 있습니다. 일시에 클라이언트를 강제로 업그레이드하는 것은 불가하므로 일정 기간 동안 서비스는 신구 버전 API를 모두 지원해야 합니다. HTTP 기반의 REST API라면 URL에 메이저 버전 번호를 삽입할 수 있습니다(예: 버전 1 경로는 앞에 /v1/를, 버전 2 경로는 /v2/를 붙임).

HTTP 컨텐트 협상(content negotiation)을 이용해서 MIME 타입 내부에 버전 번호를 끼워 넣는 방법도 있습니다. 가령 버전 1.X의 주문은 클라이언트가 이렇게 요청합니다.

GET /orders/xyz HTTP/1.1
Accept: application/vnd.example.resource+json; version=1
...

클라이언트가 버전 1.X 응답을 기대한다고 주문 서비스에 지시한 것입니다.

여러 버전의 API를 지원하려면 API가 구현된 서비스 어댑터에 신구 버전을 올바르게 중계하는 로직이 있어야 합니다. API 게이트웨이는 거의 반드시 버저닝된 API를 사용하며, 심지어는 구 버전 API도 여러 버전을 지원해야 하는 경우도 있습니다(8장).