🌿 중급 백엔드
API 버전 관리는 어떻게 하나요?
쉽게 이해하기
스마트폰 앱이 업데이트되어도 이전 버전을 쓰는 사람들은 계속 사용할 수 있죠. API 버전 관리도 같은 원리예요. 새 기능을 추가하면서도 기존 사용자들에게 피해를 주지 않으려는 거예요.
핵심 정리
API 버전 관리는 기존 사용자에게 영향 없이 새로운 기능을 추가하거나 변경할 수 있게 해줍니다.
자세히 알아보기
API 버전 관리는 크게 세 가지 방식이 있습니다. URL에 버전을 명시하는 방법(/v1/users, /v2/users), 헤더에 버전을 담는 방법(Accept: application/vnd.api+json;version=2), 쿼리 파라미터로 전달하는 방법(/users?version=2)이 있죠.
가장 많이 쓰이는 방식은 URL에 버전을 명시하는 겁니다. 직관적이고 브라우저에서도 바로 테스트할 수 있어서 개발자 친화적이거든요. 예를 들어 /api/v1/products로 시작했다가, 응답 구조를 크게 바꿔야 할 때 /api/v2/products를 새로 만드는 거죠.
실무에서는 메이저 버전(v1, v2)은 호환되지 않는 큰 변경이 있을 때만 올리고, 마이너한 추가 기능은 같은 버전 안에서 추가하는 게 일반적입니다. 중요한 건 구버전 API도 일정 기간 유지해줘야 한다는 점이에요. 갑자기 서비스가 안 되면 사용자들이 큰 피해를 보니까요.
보통 6개월에서 1년 정도 유예 기간을 두고, 구버전 사용자들에게 마이그레이션 가이드를 제공합니다.