API 버전 관리

API 버전 관리를 위한 최고의 예제는 무엇입니까?

보통 개발에서의 변경사항과 새로운 기능은, 클라이언트가 API를 사용하고 있는 도중에도 지속적으로 발생합니다.

이때, 클라이언트 코드와 서버 코드가 제어하기 어려울 정도로 변경 되어야 할 필요성이 생긴다면, 새로운 버전의 API를 도입하여 기능을 개발 할 수 있습니다.

새로운 버전의 API 를 도입하는 것은 클라이언트에게는 완곡한 표현의 서비스 종료 공지와 동일하며,

서비스에게는 구버전을 deprecated 할 수 있는 정중한 공지입니다.

REST API에서의 Versioning 관리 방법은 다양한 방법이 있는데, 일부 유명한 서비스에서는 아래와 같이 관리하고 있습니다.

- google map : https://developers.google.com/maps/documentation/javascript/versions https://maps.googleapis.com/maps/api/js?v=3.31 - git hub : https://developer.github.com/enterprise/2.13/v3/

http(s)://[hostname]/api/v3 최신버전의 경우, 버전을 붙이지 않으면 자동으로 최신 버전으로 api call - twitter : https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets.html https://api.twitter.com/1.1/search/tweets.json - youtube : https://developers.google.com/youtube/v3/getting-started https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key;=YOUR_API_KEY - naver : https://developers.naver.com/docs/common/openapiguide/apilist.md#%EB%B9%84%EB%A1%9C%EA%B7%B8%EC%9D%B8-%EB%B0%A9%EC%8B%9D-%EC%98%A4%ED%94%88-api https://openapi.naver.com/map/v3/maps https://openapi.naver.com/map/v1/geocode https://openapi.naver.com/map/v2/reversegeocode

교과서 적으로 api 버전을 관리하기 위해서는 아래와 같은 3가지 방법이 있으나,

최근에는 URL을 통한 버전 관리를 많이 사용하고 있습니다.

1. URL을 통한 버전 관리

HTTP GET : https://haveibeenpwned.com/api/v2/breachedaccount/foo

2. custom request header를 통한 버전 관리

HTTP GET : https://haveibeenpwned.com/api/breachedaccount/foo

api-version: 2

3. content type을 통한 버전 관리

HTTP GET : https://haveibeenpwned.com/api/breachedaccount/foo

Accept: application/vnd.haveibeenpwned.v2+json

이런 api version 관리를 위한 코드 작성 및 소스 파일 패키징 방식도 다양하게 이루어집니다.

1. 각 api에서 version을 관리하는 방식

@RequestMapping("/")

public class RestController {

@GetMapping("/v{version}/data")

public Token getData(@PathVariable(value = "version") String version, String params) {

;;

}

}

2. version 별로 api를 생성하는 방식

참고 문헌

1. Your API versioning is wrong, which is why I decided to do it 3 different wrong ways

- https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

2. django rest framework api guide

- http://www.django-rest-framework.org/api-guide/versioning/

3. yiiframework rest versioning guide

- https://www.yiiframework.com/doc/guide/2.0/en/rest-versioning

4. best practices for api versioning

- https://stackoverflow.com/questions/389169/best-practices-for-api-versioning

from http://hajiz.tistory.com/44 by ccl(S) rewrite - 2020-03-06 18:20:38