🌿 중급 백엔드
API 버전 관리는 왜 하나요?
쉽게 이해하기
스마트폰 앱을 떠올려보세요. 카카오톡이 새 버전이 나와도 구버전을 쓰는 사람들도 한동안 문제없이 사용할 수 있잖아요. API 버전 관리도 마찬가지예요. 새로운 기능을 추가하거나 구조를 바꿔도, 예전 방식으로 접속하는 사람들은 계속 작동하도록 해주는 거죠.
핵심 정리
API가 변경되어도 기존 사용자가 영향받지 않도록 여러 버전을 동시에 제공하는 방식이에요.
자세히 알아보기
API 버전 관리는 API를 업데이트할 때 기존 사용자에게 영향을 주지 않기 위한 전략입니다. 소프트웨어는 계속 발전하는데, API를 갑자기 바꾸면 이미 그 API를 쓰고 있던 모든 앱과 서비스가 동시에 망가지는 끔찍한 상황이 벌어질 수 있어요.
일반적인 버전 관리 방식은 세 가지입니다. URL에 버전을 넣는 방식(예: /api/v1/users, /api/v2/users), 헤더에 버전을 명시하는 방식(예: Accept: application/vnd.myapi.v2+json), 쿼리 파라미터를 쓰는 방식(예: /api/users?version=2)이 있어요. 실무에서는 URL에 버전을 명시하는 방식이 가장 직관적이고 많이 쓰입니다.
실제 사례를 보면, 트위터 API는 v1.1에서 v2로 넘어갈 때 약 2년간 두 버전을 동시에 제공했어요. 이렇게 하면 개발자들이 여유를 갖고 새 버전으로 마이그레이션할 수 있죠. 반대로 버전 관리 없이 API를 바꾼 사례도 있는데, 인스타그램이 2018년 API 정책을 갑자기 바꿨을 때 수많은 서드파티 앱들이 한순간에 작동을 멈췄습니다.
버전 관리의 핵심은 '하위 호환성(Backward Compatibility)'입니다. 새 버전을 출시해도 구버전 사용자들이 최소 6개월~1년은 문제없이 쓸 수 있도록 보장하는 게 일반적입니다. 물론 영원히 구버전을 유지할 순 없으니, 충분한 공지 기간을 두고 단계적으로 지원을 종료(Deprecation)하는 전략을 세워야 해요.