API 버전 관리는 이미 API를 쓰고 있는 클라이언트를 깨뜨리지 않으면서 API를 발전시키기 위한 전략입니다. 한 번 공개된 API는 계약(contract)이 되어, 필드 이름을 바꾸거나 응답 구조를 재편하면 수많은 통합이 한꺼번에 무너질 수 있습니다. 버전 관리의 목표는 바꿔도 되는 변화와 버전을 갈라야 하는 변화를 구분하고, 후자를 안전하게 전환하는 것입니다.
어디에 버전을 담을까: 세 가지 방식
버전 정보를 요청의 어디에 실을지에 따라 세 갈래가 있습니다.
- URI 경로(
/v1/users): 가장 흔하고 직관적입니다. URL만 봐도 버전을 알 수 있고, 브라우저·curl로 테스트하기 쉽습니다. 단점은 같은 리소스가 버전마다 다른 URL을 갖게 되어 'URI는 리소스를 가리켜야 한다'는 REST 순수주의와 어긋난다는 점입니다. - 헤더(
Accept: application/vnd.example.v2+json또는 커스텀X-API-Version: 2): URL은 그대로 두고 협상으로 버전을 고릅니다. 깔끔하지만 눈에 잘 안 보여 디버깅·문서화가 번거롭고, 버전을 빠뜨리면 기본 버전으로 조용히 처리됩니다. - 쿼리 파라미터(
/users?version=2): 구현이 쉽지만 캐시 키가 지저분해지고, 파라미터를 빠뜨렸을 때의 기본 동작을 명확히 정해야 합니다.
GET /v1/users/u_92311 HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v2+json
X-API-Version: 2미디어 타입 버전 관리
헤더 방식의 정교한 형태가 미디어 타입(콘텐츠 협상) 버전 관리입니다. Accept 헤더에 벤더 미디어 타입(application/vnd.example.v2+json)을 실어 클라이언트가 원하는 표현 버전을 요청하고, 서버는 콘텐츠 협상으로 응답합니다. URI를 리소스 식별자로 순수하게 유지한다는 점에서 이론적으로 가장 'RESTful'하지만, 실무에서는 진입장벽과 도구 지원 부족 때문에 경로 방식만큼 널리 쓰이지는 않습니다.
언제 버전을 올려야 하나
핵심 원칙은 하위 호환을 깨는(breaking) 변경일 때만 버전을 올린다는 것입니다. 무엇이 breaking이고 무엇이 아닌지 팀 안에서 명확히 정의해 두어야 합니다.
- 호환 유지(버전 유지 가능): 새 엔드포인트 추가, 응답에 새 필드 추가, 새 선택적(optional) 요청 파라미터 추가, 새 오류 코드 추가.
- 호환 파괴(버전 상승 필요): 필드 제거·이름 변경, 필드 타입 변경, 필수 파라미터 추가, 응답 구조 재편, 오류 의미 변경, 기본 동작 변경.
- 관용의 법칙(robustness principle): 클라이언트는 모르는 필드를 무시하도록 만들면, 서버의 '필드 추가'가 breaking이 아니게 됩니다.
폐기 알리기: Deprecation과 Sunset
구 버전을 없앨 때는 예고 없이 끊지 말고 표준 헤더로 미리 알립니다. Deprecation 헤더는 해당 응답(또는 엔드포인트)이 폐기되었음을, Sunset 헤더는 실제로 응답을 중단할 날짜·시각을 알립니다. Link 헤더로 마이그레이션 문서를 함께 가리키면 더 친절합니다.
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migrating-to-v2>; rel="deprecation"
Content-Type: application/json실무 권고 — 대부분의 팀에는 URI 경로 버전(/v1, /v2) 이 가장 실용적입니다. 눈에 보이고, 캐시·라우팅·문서화가 쉬우며, 도구 지원이 좋기 때문입니다. 다만 버전을 남발하지 마세요. /v2, /v3로 자주 갈라지면 여러 버전을 동시에 유지·보수하는 비용이 폭증합니다. 실제로는 가능한 한 하위 호환을 유지해 한 메이저 버전을 오래 쓰고, 정말 불가피한 대개편에서만 새 버전을 여는 것이 건강합니다. 그리고 새 버전을 내면 구 버전에 대한 명확한 폐기 일정(Deprecation·Sunset) 과 마이그레이션 가이드를 반드시 함께 제공하세요.