REST API 버전관리 필요성과 그 방법

할루

# API 버전관리 필요성 몰랐던 썰

연구소로 넘어오기 전, 그룹웨어 운영팀에 있을 때,

그룹웨어 모바일 앱 API 운영을 맡은 적이 있었다.

그 때, 모바일 앱 담당 책임님이 API를 수정하거나 신규로 딸때는

부디 API에 '_v2' 와 같은 postfix를 붙여달라고 항상 신신당부를 하셨다.

장애 위험있다고 하셨는데, 그 당시에는 솔직히 좀 이해가 안됬었다.

왜냐면 난 클린코드가 더 중요해서 사용하지 않는 메소드를 남겨두는 거 자체가 찝찝했다.

장애가 날 확률도 적다고 생각했었다.

근데, 이번에 장애가 발생할수도 있다는 것을 체감했다.

 

# API 버전관리 안할 때 에러 예시

 

아주 극단적인 예이긴 하지만,

예를 들어서, API Response 스펙을 변경하는 경우(version2로 업데이트),

APP을 기존에 설치한 사용자의 폰에는 아직 version1의 APP이 있고, API version1에 맞는 처리를 하고 있을 것이다. 하지만 API를 호출하면 version2의 스펙이 response 되므로 에러가 발생한다.

API Resquest 스펙이 변경되는 경우에도 동일하다.

 

그래서 API수정을 할떄는 항상 하위호환성을 고려해고 버전관리를 해야한다.

 

#버전관리 방법

버전관리 방법에 대해 나열해본다.

 

방법1. 컨트롤러 단에서 URI를 이용한 방법

• @GetMapping("/api/v1/users") 를 매핑하는 컨트롤러 메소드 getUserV1()과 @GetMapping("/api/v2/user")를 매핑하는 컨트롤러 메소드 getUserV2()로 정의

 

방법2. Tomcat 단에서 URI를 이용한 방법

• Spring의 application.properties 또는 Tomcat의 server.xml 설정파일
• 그 외에 배포 환경설정파일에서 Context Path를 "/api/v1"으로 설정
• V2 를 만들고 싶다면, Context Path가 "/api/v2"로 설정된 빌드파일 배포(톰캣을 새로 띄우거나 네트워크 단에서 분배하거나 여러방법이 있음)

 

방법3. MIME TYPE을 이용한 방법

• MIME TYPE(마임 타입)이란 예전에 음악 등 바이너리 파일들을 이메일에 동봉하여 전송할때 이메일 시스템에 파일 형식을 알리기위해 사용된 인코딩 방식이라 한다.
• 아무튼, 요즘에는 사용하지 않지만 이거를 이용해서 버전을 명시할 수 있다.
• 마임타입의 전체 종류는 여기서 볼수 있다. 흔히 버전관리에서는 vnd.company.appv1+json 타입을 사용한다. https://developer.mozilla.org/ko/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_type

MIME 타입의 전체 목록 - HTTP | MDN

 

@GetMapping(value = "/users/{id}", produces = "application/vnd.company.appv1+json")

@GetMapping(value = "/users/{id}", produces = "application/avnd.company.appv2+json")

 

방법4. 파라미터를 이용한 방법

• @RequestParam("version") String version
• /api/user?version=1 
• 파라미터를 이용한 방법은 그닥 추천하진 않는다. 비즈니스 로직 상 필요 파라미터와 구분하기 힘들고, 왠지 클린하지 못한 기분..

 

그럼 20000