API 버전 관리, 어떻게 해야 할까? 개발자들의 다양한 의견을 살펴보자!
API 버전 관리 방식에 대한 다양한 접근 방식(Various Approaches)이 존재하며, URL 경로에 버전 정보를 포함하는 방식에 대한 비판적 시각도 존재함
SemVer(Semantic Versioning)를 API에 적용하는 방식과, /v1/, /v2/와 같은 경로 기반 버전 관리 방식의 장단점이 논의됨
Google의 API 설계 가이드라인(API Design Guidelines)과 Buttondown의 API 버전 관리 사례가 소개됨
속성 이름 변경과 같은 API 변경(API Changes)에 대한 대응 전략으로 속성 중복, 마이그레이션(Migration) 정의 등이 제시됨
URL 경로 기반 버전 관리 vs SemVer
논의에서는 URL 경로에 `/v1/`과 같은 버전 정보를 포함하는 방식이 SemVer와 충돌할 수 있다는 점을 지적한다. SemVer(Semantic Versioning)의 세부 버전(major.minor.patch)과 URL 경로의 `/v1/`이 중복되어 API 계약(API Contract)을 두 곳에서 관리해야 하는 문제가 발생할 수 있다는 것이다. API 계약(API Contract)의 분산은 유지보수(Maintenance) 및 배포(Deployment) 과정에서 혼란을 야기할 수 있다.
Google의 API 설계 가이드라인
Google의 API 설계 방식이 소개되었으며, AIP-185(API Versioning) 및 AIP-180(Backwards Compatibility)와 같은 가이드라인이 제시되었다. Google의 API 설계는 특정 환경에 맞춰져 있지만, API 설계 시 유용한 아이디어를 제공한다. 특히, API 설계(API Design) 시 하위 호환성(Backwards Compatibility)을 유지하는 방법에 대한 구체적인 지침을 제공하며, 이는 API 사용자에게 안정적인 서비스를 제공하는 데 중요한 요소로 작용한다.
속성 변경에 대한 대응 전략
속성 이름 변경과 같은 API 변경에 대한 대응 전략으로 속성 중복(Duplication) 방식이 제시되었다. 속성 이름을 변경해야 할 경우, 기존 속성을 유지하면서 새로운 이름의 속성을 추가하는 방식이다. 하지만, 입력 속성의 경우 클라이언트가 두 속성에 서로 다른 값을 전송하는 문제가 발생할 수 있다. 이러한 경우, 새로운 속성 우선(New Name Takes Precedence)과 같은 규칙을 적용할 수 있지만, Read-Modify-Write 시퀀스(Read-Modify-Write Sequences)에서는 문제가 발생할 수 있다.
Buttondown의 API 버전 관리 사례
Buttondown의 API 버전 관리 방식은 API 소비자가 헤더(Header)를 사용하여 특정 API 버전을 고정할 수 있도록 지원한다. 이는 API 제공자가 변경을 수행하면서도 소비자의 호환성(Compatibility)을 유지할 수 있도록 돕는다. API 마이그레이션(API Migration)을 정의하여 이전 버전의 API를 사용하는 소비자가 최신 버전으로 쉽게 전환할 수 있도록 지원하는 방식이다. 하지만, HTTP 요청 헤더(HTTP Request Header)를 사용한 버전 관리는 특정 상황에서 문제를 야기할 수 있다는 지적도 있다.
