변경 분류
필드 추가, 의미 변경, 필드 삭제, 상태 코드 변경을 호환성 기준으로 나눈다.
버전 경계
같은 handler에서 분기할지 controller를 나눌지 영향 범위로 결정한다.
공지와 계측
deprecated endpoint 사용량을 로그와 metric으로 확인한다.
제거
사용량이 줄고 공지 기간이 지나면 클라이언트와 함께 제거한다.
URI version
명시적 경로
/v1/users처럼 사용자가 보기 쉬운 방식
라우트 중복 증가
Header
계약 협상
Accept-Version 같은 header로 버전 선택
클라이언트 도구 지원 확인
Additive
호환 변경
새 optional 필드 추가는 보통 안전
클라이언트 strict parser 한계
Breaking
비호환 변경
필드 제거, 타입 변경, 의미 변경, 오류 코드 변경
새 버전 필요