[API 설계] API Versioning

1. 개요

API 변경 관리를 위해 버저닝 정책을 적용해야 한다. APIM 도입 시 각 API는 클라이언트에게 ‘상품’ 개념으로 제공되게 된다. 따라서 API 버전을 통한 라이프사이클(Lifecycle) 관리가 필요하다. 또한 기술적으로는 버전 변경 시 반드시 하위 호환성을 고려해야 한다.

2. 버저닝 (Versioning)

2.1. 버전 포맷

버전 정보를 관리하는 기본 포맷은 다음과 같다.

MAJOR.MINOR.REVISION

• 기존 버전과 호환되지 않게 API가 변경된 경우 MAJOR 버전을 올린다.
• 기존 버전과 호환되면서 새로운 기능이 추가된 경우 MINOR 버전을 올린다.
• 기존 버전과 호환되면서 버그를 수정한 경우 REVISION 버전을 올린다.

관리용 목적으로 버전을 사용하는 경우, 즉 APIM에 API를 등록한다거나 API 스펙 문서 상에서 버전 정보를 사용하는 경우에는 위와 같은 포맷의 버전을 사용하면 된다.

2.2. URI 버전 관리

URI 상에 버전 번호를 관리하는 항목을 추가하여 API에 대한 버전을 관리한다. 이때는 버전 포맷 중 MAJOR 정보만 이용하며 접두사 v를 이용해 v1, v2와 같은 형태로 사용하면 된다.

{serverRoot}/{apiName}/{apiVersion}/{subResource}

• {serverRoot} : IP 및 포트 정보 또는 호스트명
• {apiName} : API 명
• {apiVersion} : API 버전 정보 ex) v1, v2
• {subResource} : API에 속해있는 하위 리소스명

예를 들어 ‘Product Catalog Management’ API의 MAJOR 버전이 2인 경우 다음과 같이 URI를 정의할 수 있다.

https://{host:ip}/product/productCatalogManagement/v2/productSpecification

이와 같은 URI형식을 이용함으로써 API 변경 시에 기존 버전과 새로운 버전을 분리하여 여러 버전의 API를 동시에 제공할 수도 있다. 단 이 경우 API Lifecycle 정책을 함께 고려해야 한다. 예를 들어 기존 버전의 경우 특정 시기에 사용안함(deprecated) 상태로 만들었다가 더 이상 사용되지 않는 시점에 폐기(retired) 상태로 만들어 EOL (End-Of-Life) 공지 후 삭제 하는 등과 같은 API Lifecycle 관리가 필요하다.

2.3. 하위 호환성

버전 변경 시 반드시 하위 호환성을 고려해야 한다. API 변경 시에 하위 호환성이 유지된다면 MINOR 또는 REVISON 버전을 올리고, 하위 호환성에 위반되는 경우에는 MAJOR 버전을 올려야 한다.

 

하위 호환성을 유지하면서 API가 변경되는 대표적인 경우는 다음과 같다.

• 새롭게 추가된 데이터 객체 (또는 객체 내 세부 필드)에 대한 사용 여부가 선택사항
• 기존 데이터 필드에서 허용 가능한 값의 크기 증가
• 열거 데이터형 사용 시 기존 항목이 유지된 상태에서 새로운 항목 추가
• 기존 오퍼레이션이 유지된 상태에서 새로운 오퍼레이션 추가
• 오퍼레이션에서 사용하는 파라미터가 기존 것은 그대로 유지된 상태이고 새로 추가된 것은 선택사항

하위 호환성을 유지하지 못하면서 API가 변경되는 대표적인 경우는 다음과 같다.

• 서비스, 인터페이스, 필드, 메소드 삭제 또는 이름 변경
• 새롭게 추가된 데이터 객체 (또는 객체 내 세부 필드)가 필수 항목
• 열거 데이터형 사용 시 기존 항목 삭제 또는 이름 변경
• HTTP 바인딩 변경
• 기 존재하는 요청에 대한 동작 변경
• URL 포맷 변경