🎞️ API 버저닝 가이드 | 어디에 버전을 둘까?

버저닝 방식

호스트

리소스 경로

버전 번호

동시에 운영할 버전 개수

헤더 이름 (헤더 방식)

벤더 토큰 (Accept 방식)

요청 예시

명령줄로 보내기

같은 리소스를 가리키는 주소 수-

버전마다 생기는 캐시 항목 수-

Vary 헤더 필요 여부-

주소만 보내 재현 가능

유지할 경로 패턴 수-

네 방식이 무엇을 깨뜨리는가

방식	캐시	링크 공유	클라이언트 수정	중간 프록시에서 보이는가
URL 경로	주소가 달라 저절로 나뉨	주소만 보내면 그대로 재현	기본 주소 한 곳만 바꾸면 됨	보임
커스텀 헤더	Vary 를 보내지 않으면 다른 버전 응답이 섞임	주소만으로는 버전이 전달되지 않음	요청을 만드는 모든 자리에 헤더를 더해야 함	헤더를 들여다봐야 보임
쿼리 파라미터	주소가 달라 나뉘지만 파라미터 순서·누락에 민감	주소만 보내면 그대로 재현	질의 문자열을 만드는 자리마다 더해야 함	보임
Accept 협상	Vary: Accept 가 필요하고 캐시 적중률이 낮아짐	주소만으로는 버전이 전달되지 않음	Accept 를 직접 다뤄야 함	헤더를 들여다봐야 보임

어느 방식이 권장이라고 단정하지 않습니다. 공인된 권장 방식은 없고, 캐시를 어디에 두는지와 클라이언트를 얼마나 통제할 수 있는지에 따라 유불리가 달라집니다. 이 도구는 각 방식이 무엇을 깨뜨리는지 보여 주고 요청 예시를 만들어 줍니다.

도구 설명

버전을 경로에 둘지, 헤더에 둘지, 쿼리 파라미터로 받을지, Accept 로 협상할지 고르면 그 방식으로 실제 요청이 어떻게 생기는지 보여 줍니다. 요청 줄과 헤더를 그대로 적어 주고 명령줄로 보낼 수 있는 형태도 함께 만들어 줍니다. 호스트와 경로, 버전 번호, 헤더 이름, 벤더 토큰을 바꾸면 결과가 바로 따라 바뀝니다.

함께 계산하는 것은 캐시와 공유에 미치는 영향입니다. 같은 리소스를 가리키는 주소가 몇 개가 되는지, 버전마다 캐시 항목이 몇 개 생기는지, Vary 응답 헤더가 필요한지, 주소만 보내도 같은 결과를 재현할 수 있는지 방식마다 다릅니다. 헤더나 Accept 로 버전을 구분하면서 Vary 를 보내지 않으면 공용 캐시가 먼저 저장한 버전을 다른 버전 클라이언트에게 그대로 내놓습니다.

어느 방식이 권장이라고 단정하지 않습니다. 2026년 10월 기준 공인된 권장 방식은 없고, 캐시를 어디에 두는지와 클라이언트를 얼마나 통제할 수 있는지에 따라 유불리가 달라집니다. 이 도구는 버전 번호를 올릴 시점을 판단해 주지 않고, 호환성이 깨졌는지 검사하지도 않습니다.

자주 묻는 질문

헤더로 버전을 구분하면 왜 Vary 가 필요한가요?

공용 캐시는 기본적으로 주소를 키로 응답을 저장합니다. 주소가 같은데 헤더에 따라 내용이 달라지면, 먼저 저장된 버전이 다른 버전을 요청한 클라이언트에게 그대로 나갑니다. Vary 에 그 헤더 이름을 적어 보내면 캐시가 헤더 값까지 키에 넣습니다.

헤더 이름에 X- 를 붙이면 안 되나요?

더 이상 권장되지 않는 관행입니다. 비표준 헤더에 X- 를 붙여 두면 나중에 그 헤더가 표준이 될 때 접두어가 있는 이름과 없는 이름이 둘 다 돌아다니게 됩니다. 그래서 처음부터 접두어 없이 쓰는 쪽이 권장됩니다.

이 도구가 하지 않는 것은 무엇인가요?

어느 방식이 권장이라고 고르거나, 버전을 올릴 시점을 판단하거나, 호환성이 깨졌는지 검사하지 않습니다. 요청 예시 생성과 캐시·공유 영향 계산만 합니다.

🎞️API 버저닝 전략 선택 가이드

네 방식이 무엇을 깨뜨리는가

관련된 도구

REST 리소스 URL 설계 가이드

API 페이지네이션 방식 선택 가이드

도구 설명

자주 묻는 질문

네 방식이 무엇을 깨뜨리는가

관련된 도구

REST 리소스 URL 설계 가이드

API 페이지네이션 방식 선택 가이드

도구 설명

자주 묻는 질문

같은 카테고리 도구