‘API Versioning’은 반드시 필요할까?

9분

2024.04.22.

2가지 API Versioning 방법

세상에 완벽한 소프트웨어는 존재하지 않습니다. 따라서 소프트웨어는 변경 사항이 생길 때마다 새로운 버전을 릴리즈합니다. 또 NPM 모듈이나 Docker 이미지 같은 경우, 1.0.1 같은 형태로 tag나 publish를 진행합니다. 이러한 방식은 Semantic Versioning이라고 하며, major.minor.patch의 정해진 포맷을 가지고 있습니다.

그렇다면 API를 배포하고 관리할 때는 Versioning을 어떻게 해야 할까요? 일반적으로 API 버전 관리에는 두 가지 방법이 쓰입니다. 바로 URI를 사용하는 방법(URI Versioning)과 HTTP Accept header를 사용하는 방법(Media Type Versioning)입니다.

URI Versioning

이 버전 관리 방식에서는 major version(v1) 하나만 사용하여 아래와 같이 표시합니다. 현재 가장 흔히 쓰이는 방법입니다.

https://yozm.wishket.com/api/v1/hello

Media Type Versioning

한편 HTTP Accept header를 적용할 때는 아래 포맷을 사용합니다.

Accept: application/json; v=1

이러한 접근 방식들은 Global Versioning이라고 하며 API 전체에 일관된 버전 관리 전략을 적용합니다. 이때 v1과 v2는 많이 다를 수 있습니다. v1에 없던 기능이 v2에서 새로 추가될 수도 있고, 일부 기능이나 속성이 변경될 수도 있으며, v1에 있던 기능 중 몇 가지가 완전히 제거될 수도 있습니다.

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) 값 이름 변경 또는 삭제
필드의 타입 변경(이전 타입까지 수용할 수 있는 경우는 해당하지 않음)
수행했던 작업이나 응답 포맷이 변경되는 경우

새롭게 리소스나 필드를 추가하는 것 괜찮다 해도 무언가 변경, 삭제가 이뤄지는 것은 문제가 되고는 합니다. 일반적으로 이때 하위 호환성(backward compatibility)을 보장하지 않기 때문이죠. 따라서 API를 사용하는 사람들로부터 많은 항의를 받을 수 있습니다.

또한 API의 v1, v2를 만드는 과정에서는 코드를 공유하는데, 어느 지점까지 가다 보면 v1과 v2가 많이 달라지고는 합니다. 결국 v2를 위해 코드를 수정하다 v1을 망가뜨릴 가능성도 올라갑니다. 보통은 v1, v2를 API의 일부(sub-section) 정도로 생각합니다. 그러나 이렇게 접근하기 보다는 API의 v1과 v2를 완전히 다른 개체로 생각하는 것이 좋습니다. 그래야만 사고를 피할 수 있습니다.

이러한 Global Versioning은 합리적인 방법처럼 보이므로 가장 흔히 쓰입니다. 그러나 이를 따라가야 하는 API 사용자들은 버전이 새로 나올 때마다 추가 작업을 요구받게 됩니다. Meta의 Facebook Graph API 같은 경우, 각 버전마다 약 2년 정도만 유효 기간을 가집니다. API 사용자가 적어도 2년에 한 번씩 바뀐 버전을 따라가기 위한 작업을 해야 한다는 뜻입니다.

API Versioning은 고객을 위한 일일까?

제가 본 어떤 API는 10년 이상 v1을 유지하고 있습니다. 아마 처음부터 Versioning이 필요 없는 API였을 것입니다. 반면 어느 API는 새로운 소비자(파트너)가 나타날 때마다 Versioning을 진행해 v20이 넘어가기도 합니다.

만약 처음부터 디자인을 잘하고, 사용자에 대한 시장 조사를 충분히 수행했다면 API의 초기 버전 몇 개는 필요하지 않을 수도 있습니다. 물론 빠르고 민첩하게 움직여야 하는 스타트업에서 흔히 시장 요구사항에 따라 버전을 빠르게 올리는 일이 생기지만, 모든 규모의 사업에서 이런 작업이 필요한 것은 아닙니다.

이처럼 버전을 빠르게 올려 관리하기 힘든 상황을 만들기보다는 다른 방법을 고려할 수 있습니다. OPEN API를 활용하여 잠재 고객이 먼저 이를 써보게 만든 다음, 충분한 피드백을 받고 정식으로 릴리즈해도 좋습니다. 고객이 나중에 통합(integration)을 위해 다시 작업하는 일을 줄일 수 있죠. 또는, 일부 고객과 빠른 협업을 위해 Postman Workspace 같은 도구를 활용하는 것도 좋은 방법입니다.

API 버전을 새로 릴리즈할 때는 보통 아래 순서로 업무를 진행합니다.

API 개발팀이 변경 사항을 만들고, 새 버전을 생성한 다음 테스트합니다.
새로운 인스턴스 및 프로덕션 파이프라인을 설정하고 배포합니다.
변경 내용을 문서화하고, 모든 고객에게 알립니다. 지원팀의 도움 요청에도 응해야 합니다.
여러 버전을 몇 달 동안 유지하며, 고객이 그사이 최신 버전으로 전환하기를 기다립니다.
기존 버전의 유효 기간까지 전환하지 않은 일부 고객은 결국 잃게 됩니다.

이런 과정은 비즈니스 목적 달성을 위한 과정으로도 보입니다. 그러나 단순히 기술 부채(tech debt)로 인해 Versioning을 하기도 합니다. API 개발자들의 입장에서야 드디어 포맷을 바꿔 부채를 털어내니 얼마나 기쁠지 모르겠지만, 이런 변화가 고객에게 어떤 가치를 제공했는지도 생각해야 합니다.

고객은 변경 사항을 검토하고, 작성된 API 문서를 살펴보며, 일부 코드를 다시 작성하고, 테스트하여 변경 사항이 문제가 없는지 확인하기 위해 시간을 투자해야 합니다. 이런 과정을 거쳐 바꾼 부분이 실제 고객의 문제와 관련이 없는 것일 수도 있습니다.

여러분이 개발한 API에 고객이 10명 있다면, 주요 버전을 릴리즈할 때 그 10명의 고객 모두 추가 작업을 해야 합니다. 최신 API로 업그레이드하는 데 평균 이틀이 걸린다면, 약 160 시간의 노동력을 소비하게 됩니다.(근무 시간 8시간 x 2일 x 10명 = 160시간) 만약 고객이 1000명이라면, 16,000 시간의 노동력이 들어갑니다. 이런 시간이 단순히 새로운 버전이 나와 앞서 버전이 사라진다는 이유로 아무 이득 없이 사라질 수 있는 겁니다. 일부 고객은 새로운 버전을 반기겠지만, 어떤 고객은 전혀 반갑지 않을 수 있습니다.

API Versioning이 필요 없는 경우는?

그러니 단순한 수정 사항은 별도 Versioning을 하지 않는 것도 방법입니다. 아래는 버전을 올릴 필요가 없는 상황들입니다.

HTTP 메서드를 추가하는 경우
HTTP 요청 및 응답으로 header, body에 필드를 옵션으로 추가하는 경우
열거형(enum type)에 허용되는 값 추가
HTTP 리소스 URI가 확장되는 경우
- /v1/foo/bar에서 /v1/foo/{param}으로 확장하는 경우
  - 단, 이 경우 API 상으로 호환성 이슈는 없어 보이지만, 클라이언트 코드상 GetBar 함수가 더는 유효하지 않아 논리적으로는 Breaking Change라고 볼 수도 있습니다.
- query를 옵션으로 추가하는 경우
에러 응답의 상세 메시지를 바꾸는 경우
- 클라이언트는 에러 메시지의 아이디만 보고 로직을 구성해야 하며, 상세 메시지를 보고 로직 구성을 하지 않습니다.
에러 메시지의 아이디 적용 범위 확장
- 새로운 에러 조건이 현재의 에러 메시지 아이디에 부합하는 경우
Rate-limit과 관련된 헤더 값 조정
- 429(Too many request) 응답 시 Rate-limit 관련 헤더를 보고 클라이언트에서 API 호출 수를 제한합니다.
- 네이버 Works API 예

API Versioning 작업으로 개발자는 기술적인 자신감을 얻을 수 있습니다. 그러나 어쩌면 안정적인 API를 위해 비용을 지불한 사용자에게 고된 작업을 강요하는 일일지도 모릅니다.

마치며

물론 API를 개발하고 아무것도 바꾸지 말라는 의미는 당연히 아닙니다. 다만 꼭 필요한 순간이 아닐 때는, 고객과의 계약(API 명세)을 유지하도록 끊임없이 노력하는 것이 중요하다는 뜻이죠. 개발자의 역할은 고객의 삶을 편하게 해주는 것입니다.

여러분이 만들었던 /api/v1은, 어쩌면 /api/beta에 가까울지도 모릅니다. 차라리 처음 API를 릴리즈 할 때 /v1을 넣지 말아 봅시다. 정말로 필요한 순간이 왔을 때, /v2 부터 Versioning을 시작해도 될 테니까요.

로그인하고 자유롭게 의견을 남겨주세요.