telexed ~ c / cc5e9d20-3dbradar:40 · otherLIVE
← 피드로
NO.
#cc5e9d20
분야
기타
출처
GeekNews
게재
2026-05-30 16:00:58
중요도
★ 4/10 — radar 40
공개 웹 API 버전 관리, `/v1`과 시맨틱 버전은 분리해야 함
FIG-0051:1

공개 웹 API 버전 관리, `/v1`과 시맨틱 버전은 분리해야 함

How to Version Public Web APIs Without Mixing Routes and Contracts

경로의 /api/v1과 API 계약의 major.minor.patch는 같은 축이 아니다. 라우팅과 호환성 정책을 섞으면 클라이언트 마이그레이션 비용이 바로 커짐.

[ 요점 ]
  1. /v1/은 라우트 경계에 가깝고, 시맨틱 버전은 API 계약 변경 규칙이다. 둘을 동일시하면 breaking change 기준이 흐려진다.
  2. major.minor.patch는 릴리스 노트와 호환성 설명에 더 잘 맞는다. URL 숫자만으로는 SDK·외부 연동자가 변경 범위를 알기 어렵다.
  3. 작은 공개 API라도 새 경로를 만들 조건과 계약 버전만 올릴 조건을 문서화해야 한다. 나중에 지원 비용을 줄이는 설계다.
원문news.hada.io/topic?id=30026원문 보기 →

// related