#0001
공개 웹 API 버전 관리, `/v1`과 시맨틱 버전은 분리해야 함
How to Version Public Web APIs Without Mixing Routes and Contracts
40radar
경로의 /api/v1과 API 계약의 major.minor.patch는 같은 축이 아니다. 라우팅과 호환성 정책을 섞으면 클라이언트 마이그레이션 비용이 바로 커짐.
/v1/은 라우트 경계에 가깝고, 시맨틱 버전은 API 계약 변경 규칙이다. 둘을 동일시하면 breaking change 기준이 흐려진다.major.minor.patch는 릴리스 노트와 호환성 설명에 더 잘 맞는다. URL 숫자만으로는 SDK·외부 연동자가 변경 범위를 알기 어렵다.- 작은 공개 API라도 새 경로를 만들 조건과 계약 버전만 올릴 조건을 문서화해야 한다. 나중에 지원 비용을 줄이는 설계다.
출처: news.hada.io/topic?id=30026원문 보기 →
