API 버전 관리

버전관리가 필요한 경우

• 클라이언트 코드와 서버 코드가 제어하기 어려울 정도로 변경 되어야할 때
• 불특정 다수의 사용자가 접속하는 OpenAPI를 지원할 때

새로운 버전의 API를 도입하는 것은 클라이언트에게는 완곡한 표현의 서비스 종료 공지가 될 수 있으며,
서비스에게는 구버전을 더 이상 사용하지 않음을 알리는 공지가 될 수 있다.

 

버전 관리 전략

다양한 방법이 있는데 많이 사용하는 방법으로는 경로, 커스텀 헤더, 콘텐츠 네고시에이션 방법이 있다.

경로

v1

GET /v1/info

v2

GET /v2/info

커스텀 헤더

v1

GET /info
api-version : 1

v2

GET /info
api-version : 2

콘텐츠 네고시에이션

v1

GET /info
Accept: application/example.1+json

v2

GET /info
Accept: application/example.2+json

도메인

v1

GET /info
Host: api.example.com

v2

GET /info
Host: apiv2.example.com

쿼리 파라미터

v1

GET /info?version=1

v2

GET /info?version=2

 

선호하지 않는 버전 관리 전략

도메인을 통한 버전관리

• 작은 변경에도 도메인이라는 비교적 큰 단위의 변경이 필요하다

쿼리 파라미터를 통한 버전관리

• Path와 파라미터의 역할을 침범할 수 있다

 

마치며...

네이버, 카카오 소셜 로그인을 구현하면서 소셜 서버에 액세스 토큰을 요청할 때 요청URL에 버전 정보가 포함되어 있었는데 당시에 이 부분이 무엇을 의미하는지 생각해보지 못했던 것 같다.

버전관리가 필요한 구체적인 상황에 대해 더 공부해봐야겠다.