API :: API Versioning ?

 

백엔드를 개발하는 개발자라면 API를 만들고 배포한 경험이 있을 것이다.

이런 API는 한번 만들고 배포하면, 삭제하거나 변경하는 게 어려워지게 되는데.. 

그래서 API Versioning으로 이를 관리하게 된다..!

 

API Versioning?

API의 변경 사항을 관리하고 추적하는 프로세스. 변경 사항을 API 사용자에게 전달하는 것 또한 포함 됨.

 

API의 생산자와 소비자가 공개인지, 비공개인지에 관계없이 API가 발전함에 따라 동기화를 유지하는 것이 중요한데ㅡ, 이를 위해 API Versioning을 한다고 생각하면 된다.

 

API Versioning 방법

보통 다른 프로그램들을 변경, 보완 해서 재 배포 할 때 1.0.1 형태로 tag 나 publish를 진행하게 되는데,

API 는 어떤 방법으로 Versioning을 진행하는 걸까?

 

URI를 사용하는 방법(URI Versioning)과 HTTP Accept header를 사용하는 방법(Media Type Versioning) 두 가지 방법이 존재한다.

※ URL는 웹 페이지를 찾는 데에만 사용되고, URI는 HTML, XML 및 기타 파일에 사용된다. URI가 조금 더 포괄적인 개념.

 

URI Versioning

해당 버전 관리 방식에서는 major version(v1) 하나만 사용하여 아래와 같이 표시한다.

가장 흔하게 쓰이는 방법이라고 한다.

https://localhost:3000/api/v1/happy

 

Media Type Versioning

HTTP Accept header를 적용하는 경우에는 아래와 같이 사용한다. Global Versioning이라고 부른다.

Accept: application/json; v=1

 

API Versioning을 하는 경우

API 공개 대상에 따른 Versioning 여부

API의 경우 공개 대상이 누군지에 따라 크게 Public, Private, Partner API로 나뉘게 된다.

 

Public API는 누구에게나 제공하는 API이기 때문에 Versioning이 필요하게 된다. 또한 웹 문서로 API의 수명 주기(LifeCycle)를 관리하여야 한다.

 

사내에서 서비스 간의 연동을 위해 사용하는 Private API에는 Versioning이 반드시 필요하다고 보기가 어렵다. 여기서 발생하는 문제는 내부적인 문제로, integration 테스트 및 품질 검사 과정에서 대부분 문제 사항이 쉽게 도출되기 때문.

 

Partner API는 그 파트너의 범위가 개발 지속성 여부에 따라 필요 여부가 달라진다. 필요한 경우도 있고, Versioning 없이 API가 관리될 여지도 있기 때문!

 

v1에서 v2로의 Versioning

공개 대상을 고려해 API Versioning을 관리하기로 했다고 한 경우, 

v1에서 v2로 가는 업데이트는 'Breaking Change'가 있을 때 진행된다.

 

Breaking Change 의 케이스

- API 리소스 엔드포인트의 이름이나 경로, HTTP 메서드를 바꾸거나 삭제하는 경우

- 열거형(enum type) 값 이름 변경 또는 삭제

- 필드의 타입 변경(이전 타입까지 수용할 수 있는 경우는 해당되지 않음)

- 수행했던 작업이나 응답 포맷이 변경되는 경우

 

API Versioning이 필요 없는 케이스

1. HTTP 메서드를 추가하는 경우

2. HTTP 요청 및 응답으로 header, body에 필드를 옵션으로 추가하는 경우

3. 열거형(enum type)에 허용되는 값 추가

4. HTTP 리소스 URI가 확장되는 경우

5. 에러 응답의 상세 메세지를 바꾸는 경우

6. 에러 메세지의 아이디 적용 범위 확장

7. Rate-limit과 관련된 헤더 값 조정

등...

 

 

문서화, 버전화를 생활화 하자!