API는 변한다. 하지만 기존 클라이언트는 깨지면 안 된다. API 버저닝은 이 문제를 해결한다. 여러 버전의 API를 동시에 유지하면서 점진적으로 마이그레이션할 수 있게 한다.
버저닝 방법은 여러 가지다. URL 경로에 버전을 넣는 방법이 가장 직관적이다. /api/v1/users처럼 경로에 버전 번호를 포함한다. 명확하고 캐싱하기 쉽다.
헤더 기반 버저닝
Accept 헤더에 버전을 명시하는 방법도 있다. application/vnd.api.v1+json 같은 형식이다. URL이 깔끔해지지만 테스트하기 불편하다. 브라우저에서 바로 확인할 수 없다.
쿼리 파라미터를 사용하기도 한다. /api/users?version=1 형식이다. 구현은 쉽지만 캐싱에 영향을 줄 수 있다.
시맨틱 버저닝
API 버전에도 시맨틱 버저닝을 적용할 수 있다. 메이저 버전은 호환되지 않는 변경, 마이너는 기능 추가, 패치는 버그 수정. 하지만 공개 API에서는 메이저 버전만 사용하는 경우가 많다.
변경 로그를 잘 관리하자. 어떤 버전에서 무엇이 바뀌었는지 문서화한다. 마이그레이션 가이드를 제공한다. 클라이언트 개발자가 업그레이드할 수 있게 돕는다.
폐기 정책
오래된 버전을 언제 폐기할지 정책을 정한다. 일반적으로 새 버전 출시 후 6개월~1년의 유예 기간을 둔다. 폐기 일정을 미리 공지한다. Sunset 헤더로 폐기 예정일을 알릴 수 있다.
Categories:
