API 버저닝
방식 비교
| 방식 | 예 | 장점 | 단점 |
|---|---|---|---|
| URL 경로 | /v1/orders | 명확, 라우팅과 캐시 쉬움 | URI가 리소스 식별을 벗어남 |
| 쿼리 파라미터 | ?version=1 | 도입 쉬움 | 누락 시 기본값이 모호 |
| 헤더 | Accept: ...v1+json | URL 유지 | 디버깅과 캐시 불편 |
| 날짜 버전 | 2026-08-01 | 세밀한 이력 관리 | 운영 복잡도 상승 |
무엇이 파괴적 변경인가
- 파괴적: 필드 삭제, 이름 변경, 타입 변경, 필수 파라미터 추가, 에러 의미 변경
- 비파괴적: 선택 필드 추가, 새 엔드포인트 추가, 응답에 값 추가
실무 포인트
- 버전을 올리는 것보다 올리지 않아도 되게 설계하는 편이 싸다. 필드 추가는 하위호환이므로 v2를 만들 이유가 없다
- 새 버전을 만들면 종료 계획을 함께 정한다. 지원 기간, 폐기 고지, 버전별 사용량 계측
- 클라이언트가 배포를 제어할 수 없는 환경(모바일 앱)은 구버전이 오래 남는다. 강제 업그레이드 경로가 필요하다
- 응답 파싱에서 미지의 필드를 허용하도록 클라이언트를 만들어 두면 서버 변경 폭이 넓어진다