개요
API 스펙이 달라지면 버전을 변경해야 할 일이 생깁니다. 이때 여러가지 전략을 사용해 클라이언트와 서버간의 API 버저닝 관리를 실현할 수 있습니다. API 버전 관리란 단순한 API 디자인을 넘어서는 주제이며, API를 통해 일하는 사람과 마찬가지로 API 디자이너는 모든 의미를 알고 있어야 합니다. 오늘은 API 버저닝을 하기 위한 전략 6가지를 살펴보겠습니다.
API 버전 관리와 구현 버전
API의 버전은 인터페이스 컨트랙트에 영향을 주느냐에 따라서 변경되는 것이 좋습니다. 예를 들어서 마이크로서비스 아키텍처를 따르고 있는 서버에서 특정 도메인 영역에 대한 서버 개발언어를 Python 에서 Go 로 변경했다 하더라도 이전 API 와 같은 역할을 한다면 API 의 버전이 올라갈 필요가 없는 것입니다.
구현 버전은 보통 시멘틱 버저닝을 따릅니다.
시멘틱 버저닝은 세 자리 숫자를 이용한 형태로 구성되어있습니다. 각 자리 숫자마다 아래와 같은 의미를 지니고 있습니다.
1. 메이저:
하위 호환성을 유지 할 수 없는 큰 변화가 생긴 경우
2. 마이너: 새로운 기능이 추가되고, 하위 호환성이 유지되는 경우
3. 패치: 하위 호환이 가능한 버그 수정의 경우
반면 API 버전은 시멘틱 버저닝과 다르게 브레이킹, 논 브레이킹을 뜻하는 두 자리의 숫자로만 구성되어있습니다.
브레이킹: 하위 호환이 불가능한 변경 ex) 응답포멧이 통째로 변경되는 경우
논 브레이킹: 하위 호환이 가능한 변경
컨슈머 관점에서 API 표현 선택
서버에서 API 버전을 명시하고 배포하면 클라이언트에서는 어떻게 사용하고 싶은 API 버전을 서버에 알릴 수 있을까요.
클라이언트(컨슈머) 가 원하는 API 를 명시하기 위한 방법은 여러가지가 존재합니다.
가장 중요한 것은 어떤 방법을 사용하냐에는 정답이 없고 현재의 팀 상황에 맞는 방법을 선택하는 것입니다.
명사 기반
경로
ex) api.test.com/v1/users, api.test.com/v2/users (가장 많이 사용되지 않을까?!?)
도메인
ex) api.test.com/users, apiv2.test.com/users
파라미터 기반
쿼리파라미터
ex) /users?version=2
커스템 헤드
ex) 헤더에 Version: 2 명시
콘텐츠 네고시에이션
ex) 헤더에 Accept: application/vnd.bank.1+json 명시
글을 마치며
해당 글은 "일상 속 사물이 알려주는 웹 API 디자인" 책을 읽고 제 개인적인 견해와 함께 정리한 글입니다.
제 견해와 생각이 들어가다보니 내용에 잘못된 부분이 존재할 수 있습니다. :)
