API 버저닝은 언제 필요하고 어떤 방식이 있나요?

API 버저닝은 기존 클라이언트와 호환되지 않는 변경이 필요할 때 사용합니다. URL 경로(/v1), 헤더, 쿼리 파라미터 방식이 있으며, 어떤 방식을 쓰든 지원 기간과 폐기 정책을 명확히 해야 운영 혼란을 줄일 수 있습니다.

핵심 개념

핵심 기준은 호환되지 않는 변경을 안전하게 도입입니다. 이 개념은 단순히 용어를 외우는 것보다, 어떤 문제를 줄이기 위해 등장했는지와 실제 코드나 운영 환경에서 어떤 trade-off를 만드는지 함께 이해하는 것이 중요합니다.

기존 클라이언트를 깨지 않으면서 응답 구조를 바꾸는 상황을 생각해보세요.

동작 흐름

1. 먼저 문제가 발생하는 조건과 입력을 확인합니다.
2. 관련된 런타임, 브라우저, 서버, 데이터 저장소의 책임을 나눠 봅니다.
3. 가장 작은 범위에서 안전한 해결책을 적용합니다.
4. 로그, 테스트, 모니터링으로 실제로 문제가 줄었는지 확인합니다.

실제 예시

앱 구버전이 아직 /v1/users 응답의 name 필드를 기대하는데 서버가 profile.name으로 바꾸면 장애가 됩니다.

실무에서 적용하는 방법

새 구조는 /v2로 제공하고 구버전 사용량을 모니터링하며 종료 일정을 공지합니다.

실무에서 주의할 점

• 사소한 필드 추가처럼 하위 호환 변경에는 새 버전이 꼭 필요하지 않을 수 있습니다.
• 개념을 적용하기 전에 현재 시스템의 규모, 병목, 장애 영향도를 함께 확인해야 합니다.
• 팀 규칙이나 프레임워크 기본 동작과 충돌하지 않는지도 점검하는 것이 좋습니다.

함께 연결해서 보면 좋은 키워드

API, 버저닝, 호환성, 운영

면접에서 짚으면 좋은 포인트

• 정의만 말하기보다 어떤 문제를 줄이기 위한 개념인지 먼저 설명하면 좋습니다.
• 장점과 함께 비용, 한계, 적용하지 않아도 되는 상황을 같이 말하면 실무 이해도가 드러납니다.

정리

한 줄로 정리하면, API 버저닝은 기존 클라이언트와 호환되지 않는 변경이 필요할 때 사용합니다입니다. 실무에서는 개념을 적용하는 조건과 적용하지 않았을 때 생기는 문제까지 함께 이해하는 것이 중요합니다.