🌿 중급 백엔드
API 버전 관리는 어떻게 하나요?
쉽게 이해하기
책이 개정판을 낼 때 '2판', '3판' 같은 식으로 표시하는 것처럼, API도 변경사항이 생기면 버전을 나눠서 관리해요. 그래야 1판을 보던 독자들이 갑자기 당황하지 않죠. 2판을 보고 싶은 사람만 골라서 볼 수 있게요.
핵심 정리
API 버전을 관리하는 방법에는 URL, 헤더, 쿼리 파라미터 방식 등이 있고, 각각 장단점이 있어요.
자세히 알아보기
API를 업데이트할 때 기존 사용자에게 영향을 주면 안 되니까 버전 관리가 필요해요. 가장 흔한 방법은 URL에 버전을 넣는 거예요. '/v1/users', '/v2/users' 같은 식이죠. 직관적이고 명확해서 많이 쓰여요.
두 번째 방법은 헤더를 쓰는 거예요. 'Accept: application/vnd.myapi.v2+json' 같은 식으로 요청 헤더에 버전을 명시하는 거죠. URL을 깔끔하게 유지할 수 있지만, 개발자가 헤더를 설정하는 걸 잊을 수 있어요.
세 번째는 쿼리 파라미터를 쓰는 방법이에요. '/users?version=2' 같은 식이죠. 간단하지만 버전이 선택사항처럼 보여서 혼란을 줄 수 있어요.
실무에서는 URL 방식을 가장 많이 써요. 명확하고 캐싱하기도 쉽거든요. 중요한 건 하위 호환성(backward compatibility)이에요. v2를 만들어도 v1을 당분간 유지해서 기존 사용자가 천천히 이전할 수 있게 해줘야 해요. 보통 6개월~1년 정도 유예 기간을 주고, 충분히 공지한 후에 구버전을 종료해요. 버전 관리를 잘하면 API를 안정적으로 발전시키면서도 사용자들에게 불편을 주지 않을 수 있어요.