[웹 API 디자인] 6. 버전 관리 팁

Created: 2023.03.03 Updated: 2023.12.19

버전 관리 팁

버전 관리는 Web API를 설계할 때 가장 중요한 고려 사항 중 하나입니다.

버전 없이 API를 출시하지 마세요. 버전은 필수입니다.

세 가지 주요 API 제공업체가 어떻게 버전 관리를 다루는지 살펴보겠습니다.

Twilio          /2010-04-01/Accounts/
salesforce.com  /services/data/v20.0/sobjects/Account
Facebook        ?v=1.0

Twilio는 URL에서 타임스탬프를 사용합니다(유럽 형식에 주의).

컴파일 시간에, 개발자는 코드를 컴파일 할 때의 애플리케이션 타임스탬프를 포함시킵니다. 그 타임스탬프는 모든 HTTP 요청에 포함됩니다.

요청이 도착하면, Twilio는 조회를 수행합니다. 타임스탬프를 기반으로 코드가 생성될 때 유효했던 API를 식별하고 그에 따라 라우팅합니다.

이것은 매우 똑똑하고 흥미로운 접근 방식입니다. 그러나 조금 복잡한 것 같습니다. 예를 들어, 타임스탬프가 컴파일 시간인지 아니면 API가 출시된 타임스탬프인지 이해하는 것이 혼란스러울 수 있습니다.

Salesforce.com은 URL의 중간에 “v20.0”을 사용합니다.

v. 표기법의 사용은 우리가 좋아하는 부분입니다. 그러나 “.0”을 사용하는 것은 인터페이스가 더 자주 변경될 수 있음을 시사하기 때문에 우리는 그것을 좋아하지 않습니다. 인터페이스의 로직은 빠르게 변경될 수 있지만 인터페이스 자체는 자주 변경되어서는 안됩니다.

Facebook도 v. 표기법을 사용하지만 버전을 선택적 매개변수로 만듭니다.

이는 문제가 될 수 있습니다. Facebook이 API를 다음 버전으로 강제로 업그레이드하면 버전 번호가 포함되지 않은 모든 앱이 중단되고 버전 번호가 추가되어야 했습니다.

REST에서 버전 번호를 어떻게 실용적으로 생각해야 할까요?

API를 버전 없이 출시하지 마세요. 버전을 필수적으로 지정하세요.

‘v’ 접두사를 사용하여 버전을 지정하세요. URL의 가장 왼쪽으로 이동하여 가장 높은 범위를 가지도록 하세요(예: /v1/dogs).

간단한 서수를 사용하세요. v1.2와 같은 점 표기법은 API에서 잘 작동하지 않는 버전 관리의 정밀성을 내포하기 때문에 사용하지 마세요. 인터페이스이기 때문입니다. v1, v2 등으로 유지하세요.

얼마나 많은 버전을 유지해야 할까요? 이전 버전을 적어도 하나 유지하세요.

얼마나 오래 버전을 유지해야 할까요? 버전을 폐기하기 전에 개발자가 반응할 수 있는 충분한 시간을 제공하세요.

6개월에서 2년까지 다양한 개발 플랫폼, 애플리케이션 유형 및 애플리케이션 사용자에 따라 다릅니다. 예를 들어, 모바일 앱은 웹 앱보다 개발하는 데 더 오래 걸립니다.

URL이나 헤더에 버전 및 형식을 넣어야 하는가?

헤더에 형식과 버전을 넣는 것이 올바른 방법이라고 생각하는 사람들이 있습니다.

여러 개의 인터디펜던트(상호 의존적인) API를 가지고 있기 때문에 버전을 헤더에 넣어야하는 경우가 종종 있습니다. 이는 대개 더 큰 문제의 증상이며, 내부 혼란을 노출시키는 것이 아니라 상단에 하나의 사용 가능한 API 퍼사드(facade)를 생성하는 것이 더 나은 방법입니다.

버전을 헤더에 넣는 것은 문제가 있는 API 설계의 증상이라는 것은 아닙니다. 아니에요!

사실, 헤더를 사용하는 것이 HTTP 표준을 활용하고, Fielding의 비전과 지적으로 일관성이 있으며, 인터디펜던트 API와 관련된 몇 가지 어려운 실제 문제를 해결하고 더 많은 이점이 있기 때문에 더 정확합니다.

하지만 우리는 대부분의 인기있는 API가 이 방법을 사용하지 않는 이유는 브라우저에서 해킹하는 것이 덜 재미있기 때문이라고 생각합니다.

우리가 따르는 간단한 규칙은 다음과 같습니다.

응답을 처리하는 로직을 변경하는 경우 URL에 넣어서 쉽게 볼 수 있도록 합니다.

OAuth 정보와 같이 각 응답에 대한 로직을 변경하지 않는 경우에는 헤더에 넣어야합니다.

이 예시들은 모두 같은 리소스를 나타냅니다.

dogs/1
Content-Type: application/json

dogs/1
Content-Type: application/xml

dogs/1
Content-Type: application/png

응답을 처리하기 위한 코드는 매우 다르게 작성될 것입니다.

헤더는 더 올바르고 여전히 강력한 API 디자인입니다.