[Spring] REST API Version 관리

Versioning

버전관리라는 것은 단순하게 사용자에게 보여주는 항목을 관리하는 것이 아닌 REST API 설계가 변경되거나 또는 Application의 구조가 변경되었을 시에도 버전을 변경해야 할수도 있다. 또한 사용자들이 어떤 버전을 사용해야 할지 가이드를 해야할 수 도 있습니다.

또한 회사, 팀마다 어떻게 Version 관리를 하는 방식은 매우 다릅니다. REST API의 새로운 버전을 오픈, 배포해도 고객들은 기존의 주 버전을 계속 사용하기를 원할수도 있고 새로운 API Version을 사용하길 원할 수도 있습니다

REST API 에서 Version을 관리하는 4가지 방법에 대해 정리하고자 합니다.

Versioning 방법

1. URI versioning
2. Request Parameter versioning
3. MIME type versioning
4. Header versioning

URI와 Request parameter를 이용하는 방법은 일반 브라우저에서 실행이 가능하나, MIME Type, header정보를 이용한 버전 관리는 일반 브라우저에서 사용할 수 없습니다.

1) URI Versioning

@GetMapping("/v1/version-test")

http://www.example.com/v1/version-test

REST API Version을 명시하는 방법중 하나는 URI 경로에 버전을 명시하는 것입니다. Facebook, Twitter, AirBnB 등에서 이 방법을 사용하고 있습니다. API의 내부적인 정보는 Majar-version.Minor-version.Release-version 형태로 사용됩니다.

이 방법은 URI을 사용하여 특정 버전의 API를 가리킵니다. 캐시 키(이 경우 URI)는 버전별로 변경되므로 클라이언트는 리소스를 쉽게 캐시할 수 있습니다. 새로운 버전의 REST API가 출시되면 캐시 내의 새로운 엔트리로 인식됩니다.

장점 : 클라이언트는 쉽게 리소스를 캐시할 수 있습니다.
단점 : 이 방법은 코드 베이스에 매우 큰 공간이 필요해집니다. 이 말의 의미는 새로운 버전이 생성된다는 것은 API 전체를 새로 분기하는 것을 의미합니다.

2) Query Request Parameter

@GetMapping(value = "/version-test/", params = "version=1")

http://www.example.com/version-test?version=1

Query Request parameter에 버전을 명시하는 방법입니다. 이는 구현 관점에서 API를 버전화하는 간단한 방법입니다.

장점 : API 버전을 쉽게 만들 수 있으며 최신 버전으로 기본 설정하기 쉽습니다.
단점 : 적절한 API 버전으로 요청을 라우팅할 때 쿼리 파라미터를 사용하는 것이 더 어렵습니다.

3) Custom header

@GetMapping(value = "/version-test", headers="X-API-VERSION=1")

postman에서 header에 X-API-VERSION을 추가하여 version을 별도로 요청 가능

REST API는 Atribute로 포함된 버전 번호와 함께 커스텀 헤더를 제공하여 버전화할 수도 있습니다. 이 접근법과 이전 두 접근법의 가장 큰 차이점은 URI에 버전 정보를 복잡하게 만들지 않는다는 것입니다.

장점 : URI를 버전 정보로 복잡하게 만들지 않습니다.
단점 : Custom Header가 필요합니다.

4) MIME type versioning

@GetMapping(value = "/version-test", produces = "application/vnd.company.appv1+json")

마지막은 MIME type을 이용한 방법입니다. 이 방법을 사용하면 API 전체를 버전화하는 대신 단일 리소스 표현을 버전화할 수 있으므로 버전 관리를 보다 세밀하게 제어할 수 있습니다. 또한 새로운 버전을 만들 때 전체 애플리케이션을 분리할 필요가 없으므로 코드 베이스에 설치 공간이 줄어듭니다. 이 접근법의 또 다른 장점은 URI 경로를 통한 버전 관리를 통해 도입된 URI 라우팅 규칙을 구현할 필요가 없다는 것입니다.
이 접근법의 결점 중 하나는 URI 버전 API보다 접근성이 떨어진다는 것입니다. 미디어 타입을 가진 HTTP 헤더가 필요하기 때문에 브라우저를 사용하여 API를 테스트하고 탐색하는 것이 더욱 어려워집니다. (Curl, Postman 등의 툴을 사용하여 테스트를 해야 합니다.)

장점: API 전체를 버전화하는 대신 단일 리소스 표현을 버전화할 수 있으므로 버전 관리를 보다 세밀하게 제어할 수 있습니다. 설치 공간을 줄일 수 있습니다. URI 라우팅 규칙을 구현할 필요가 없습니다.
단점: 미디어 타입의 HTTP 헤더가 필요하기 때문에 브라우저를 사용하여 API를 테스트하고 탐색하는 것이 더욱 어려워집니다.

Version 관리에 중요한 점

• URI 가 지저분 해지지 않도록 잘 관리해야 한다.
• 잘못된 HTTP Header 사용
• Cache로 인해 지정한 값이 제대로 반영되지 않을 수 있음.
• 요청하는 API가 웹 브라우저에서 바로 동작해야 한다.
• API 개발자 문서를 지원해야 한다.

Reference

Four REST API Versioning Strategies