REST API 버저닝 전략 — URL·헤더 어느 쪽이 정답인가

핵심 요약

API를 한번 공개하면 그걸 쓰는 클라이언트(앱·외부 연동)가 생긴다. 응답 구조를 바꾸면 그들이 깨진다. 그래서 버저닝으로 옛 버전을 유지하면서 새 버전을 낸다. 방식은 크게 URL 경로(/v1/)와 헤더 두 가지이고, 가장 중요한 건 "애초에 깨는 변경을 덜 만드는" 설계다.

1. 두 가지 방식

실무에서는 URL 경로 방식이 압도적으로 많다. 눈에 보이고 브라우저·curl로 바로 테스트되기 때문이다.

2. 무엇이 "깨는 변경(breaking change)"인가

• 필드 삭제·이름 변경, 타입 변경(문자열→숫자)
• 필수 파라미터 추가
• 응답 구조 변경(배열→객체)

반대로 필드 추가는 대개 안전하다(기존 클라이언트는 모르는 필드를 무시). 그래서 "추가는 자유, 삭제·변경은 신중"이 원칙이다.

3. 버전을 덜 올리는 설계

• 필드는 더하되 빼지 마라 — 없앨 필드는 한동안 유지하며 deprecated 표시
• 모르는 필드는 무시하도록 클라이언트를 관대하게 작성(Postel의 법칙)
• 기본값을 잘 두면 새 파라미터를 필수로 안 만들어도 된다

4. 버전을 올릴 때

• 옛 버전에 지원 종료(deprecation) 일정을 공지하고 응답 헤더로 경고
• 두 버전을 한동안 병행 운영 → 클라이언트 이전 시간 확보
• major만 버전으로(v1, v2). 사소한 변경까지 버전 올리면 관리 지옥

자주 묻는 질문

URL 방식과 헤더 방식 중 뭘 쓰나요?

특별한 이유가 없으면 URL 경로(/v1/)를 권장합니다. 눈에 보여서 디버깅·문서화·테스트가 쉽고, 대부분의 공개 API가 이 방식입니다. 헤더 방식은 "URL은 리소스만 표현해야 한다"는 원칙엔 맞지만 실무 편의가 떨어집니다.

버전을 언제 올려야 하나요?

기존 클라이언트를 깨뜨리는 변경(필드 삭제·타입 변경·구조 변경)이 필요할 때만 올립니다. 필드 추가처럼 하위호환되는 변경은 버전을 올리지 않고 같은 버전 안에서 처리하는 게 좋습니다.

옛 버전은 언제까지 유지하나요?

정답은 없지만 사용량과 계약에 따라 정합니다. 최소 수개월의 유예와 명확한 종료 공지가 관례입니다. 응답에 deprecation 경고 헤더를 넣어 이전을 유도하고, 사용량이 충분히 빠지면 종료합니다.