[Spring boot/RESTful] REST API 버전 관리

버전 관리

단순하게 사용자에게 보여주는 항목을 제어하는 용도가 아니라
REST API의 설계가 변경되거나 어플리케이션의 구조가 바뀔 때도 버전을 변경해주어야 한다.
사용자에게는 어떠한 API 버전을 사용해야 하는지 명시해야 한다.

종류

1) URI Versioning : Twitter

2) Request Parameter Versioning : Amazon

3) (Custom) Headers Versioning(MIME) : Microsoft

4) Media type Versioning(content negotiation, accept header) : Github

 

• 일반 브라우저에서 실행 가능 : URI, Request Parameter
• 일반 브라우저에서 실행 불가 : (Custom) Headers Versioning, Media type Versioning

 

유의 사항

• URI Pollution : 너무 지저분하거나 과도하게 정보를 표기하는 것은 지양
• Misuse of HTTP headers : 잘못된 헤더값 주의
• Caching : 적절히 캐시 삭제해서 제대로 된 값을 사용할 수 있도록 함
• Can we execute the request on browser?
• API Documentation

 

REST API 버전 관리

Richardson Maturity Model

Richardson Maturity Model

기본 설정

// 반환받은 User를 UserV2로 변환
UserV2 userV2 = new UserV2();

// 두 인스턴스 간에 공통된 필드가 있을 경우 해당 값을 copy함
BeanUtils.copyProperties(user, userV2); // id, name, joinDate, password, ssn
userV2.setGrade("VIP");

 

URL을 이용한 버전 관리

url에 버전을 표시함으로써 버전을 표시할 수 있다.

버전 관리는 애플리케이션의 소스 코드 뿐만 아니라 제공하려는 서비스의 리소스에 대해서도 관리해주는 것이 좋다.

@GetMapping("/v1/users/{id}") 
public MappingJacksonValue retrieveUserV1(@PathVariable int id) { ... }

 

Request Parameter를 이용한 버전 관리

params = " " 사용

// 데이터 뒤에 버전에 대한 정보가 추가적으로 전달되어야 하기 때문에 URI 뒤에 "/"가 붙는다
@GetMapping(value = "/users/{id}/", params = "version=1")

http://localhost:8088/admin/users/1/?version=1 방식으로 호출

 

Header를 이용한 버전 관리

@GetMapping(value = "/users/{id}", headers = "X-API-VERSION=2")

MIME 타입을 이용한 버전 관리

MIME 타입 → Multi-Purpose Internet Mail Extension(파일 변환)

이메일과 함께 전송되는 메일를 텍스트 문자로 변환해서 이메일 서버에 전달하기 위한 방법

// 제공하고자 하는 MIME 타입 지정
// 기존에 없던 새로운 값 -> application
// 버전 이름 : appv1
// 전달 시키조자 하는 타입 : json
@GetMapping(value = "/users/{id}", produces = "application/vnd.company.appv1+json")