Posted On 2026년 02월 15일

API 버저닝 전략

nobaksan 0 comments
여행하는 개발자 >> 기술 >> API 버저닝 전략

API는 변한다. 하지만 기존 클라이언트는 깨지면 안 된다. API 버저닝은 이 문제를 해결한다. 여러 버전의 API를 동시에 유지하면서 점진적으로 마이그레이션할 수 있게 한다.

버저닝 방법은 여러 가지다. URL 경로에 버전을 넣는 방법이 가장 직관적이다. /api/v1/users처럼 경로에 버전 번호를 포함한다. 명확하고 캐싱하기 쉽다.

헤더 기반 버저닝

Accept 헤더에 버전을 명시하는 방법도 있다. application/vnd.api.v1+json 같은 형식이다. URL이 깔끔해지지만 테스트하기 불편하다. 브라우저에서 바로 확인할 수 없다.

쿼리 파라미터를 사용하기도 한다. /api/users?version=1 형식이다. 구현은 쉽지만 캐싱에 영향을 줄 수 있다.

시맨틱 버저닝

API 버전에도 시맨틱 버저닝을 적용할 수 있다. 메이저 버전은 호환되지 않는 변경, 마이너는 기능 추가, 패치는 버그 수정. 하지만 공개 API에서는 메이저 버전만 사용하는 경우가 많다.

변경 로그를 잘 관리하자. 어떤 버전에서 무엇이 바뀌었는지 문서화한다. 마이그레이션 가이드를 제공한다. 클라이언트 개발자가 업그레이드할 수 있게 돕는다.

폐기 정책

오래된 버전을 언제 폐기할지 정책을 정한다. 일반적으로 새 버전 출시 후 6개월~1년의 유예 기간을 둔다. 폐기 일정을 미리 공지한다. Sunset 헤더로 폐기 예정일을 알릴 수 있다.

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

Related Post

태양을 병에 담는 과학, 그리고 우리의 에너지 미래

태양이 지면 전기는 사라질까? 수십 년간 인류는 이 질문에 대한 답을 찾아 헤맸고, 이제 과학자들이…

디지털 신원 확인의 대가: 내 개인정보는 어디로 가는가

신원 확인 버튼을 누르는 순간, 우리는 무엇을 건네주고 있는 걸까. 40대 중반이 되면서 온라인 서비스들이…

AI가 디자인을 흉내낼 때, 우리는 무엇을 잃고 있는가

디자인이란 결국 선택의 연속이다. 색상 팔레트에서 한 톤을 고르는 일, 여백의 크기를 8픽셀과 12픽셀 사이에서…