🌳 고급 api
API 버전 관리 전략은?
쉽게 이해하기
스마트폰 앱이 업데이트되어도 예전 버전을 쓰는 사람도 있죠. 마찬가지로 API도 새 버전을 만들 때 구버전을 쓰는 클라이언트가 갑자기 작동을 멈추면 안 돼요. 그래서 '/v1/users'와 '/v2/users'처럼 버전을 명시해서, 준비된 클라이언트만 새 버전으로 옮겨가게 하는 거예요.
핵심 정리
API 버전 관리는 기존 사용자에게 영향 없이 API를 개선하는 전략이에요.
자세히 알아보기
API 버전 관리는 세 가지 방식이 있어요. 첫째, URL에 버전을 넣는 방식이에요. 'api.example.com/v1/users', 'api.example.com/v2/users'처럼 경로에 명시하는 거죠. 가장 직관적이고 많이 쓰이지만, URL이 길어지는 단점이 있어요.
둘째, Header에 버전을 넣는 방식이에요. 'Accept: application/vnd.example.v1+json'처럼 HTTP 헤더로 버전을 지정해요. URL은 깔끔하지만, 개발자가 헤더를 까먹거나 잘못 설정할 위험이 있어요. GitHub API가 이 방식을 써요.
셋째, 쿼리 파라미터로 버전을 넣는 방식이에요. 'api.example.com/users?version=1'처럼 쓰는 건데, 잘 안 쓰이는 편이에요. 캐싱이 복잡해지고 REST 원칙에도 맞지 않아요.
실무에서는 URL 버전 관리를 가장 많이 써요. Stripe, Twitter, AWS 같은 대형 서비스가 이 방식을 채택했어요. 중요한 건 버전을 바꿀 때 '호환성을 깨는 변경(Breaking Change)'만 새 버전으로 만들고, 필드 추가 같은 호환 가능한 변경은 같은 버전에서 하는 거예요.
또한 구버전을 언제까지 지원할지 미리 공지하는 '지원 중단(Deprecation) 정책'이 중요해요. 보통 1~2년 정도 유예 기간을 주고, 충분히 경고한 뒤에 구버전을 종료해요. 무작정 구버전을 유지하면 유지보수 비용이 기하급수적으로 늘어나니까요.