API :: API Versioning ?

BACKEND

neeon 2024. 4. 26. 09:34

728x90

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

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

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

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

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

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

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

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

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

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

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

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

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

Accept: application/json; v=1

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

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

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

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

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

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

Breaking Change 의 케이스

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

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

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

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

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

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

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

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

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

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

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

등...

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

728x90