API 버전 관리 방법에 대한 장단점은 무엇입니까?

Question

어떤 예에서는 API 버전을 만드는 두 가지 방법을 알 수 있습니다.

그중 하나는 URL에서 버전을 사용하고 있습니다.

/api/v1/products

다른 하나는 컨텐츠 유형 헤더와 허용 헤더를 사용하여 서버로 전송되는 데이터의 API 버전을 표시합니다.

Content-Type=application/vnd.company.v2+xml

이 접근법의 장단점은 무엇입니까? 각 접근 방식을 사용할 수있는 유스 케이스는 무엇입니까?

Answer 1

URL 자체 (/v1/)에 버전 번호가있는 데 익숙했습니다. 개인적으로 이것은 훨씬 더 깨끗한 접근법이라고 생각합니다.이 방법으로 최종 사용자 (또는 개발자)는 HTTP 헤더를 처리 할 필요가 없으며 필요에 따라 다른 버전의 API에 액세스하기 위해 나머지 API/호출을 단순히 수정할 수 있습니다.

다른 언어로 HTTP API 중 일부가 HTTP 헤더를 완전히 지원하지 않을 수도 있으므로 항상 최종 사용자가 API를 가장 쉽게 사용할 수 있도록합니다. URL을 다시 작성하는 것이 가장 간단한 방법이며 HTTP를 지원하는 모든 것과 함께 작동해야합니다.

마지막으로 URL을 사용하여 API 버전을 지정할 수있게하면 웹 브라우저를 사용하여 간단한 테스트가 가능합니다. 버전 작성을 HTTP 헤더에 통합하는 경우 개발자는 프로그래밍 언어를 사용하여 테스트를 수행해야합니다.

Answer 2

두 메커니즘 모두 유효합니다. 어떤 길을 따라야하는지 알기 위해 소비자를 알아야합니다. 일반적으로 기업 및 학문적 인 사람들과 협력하는 것은 개발자가 자원 헤더 버전을 향한 경향이 있습니다. 그러나 고객이 소규모 비즈니스 인 경우 URL 버전화 접근 방식이 더 널리 사용됩니다.

다음은 내가 찾을 수있는 장단점입니다 (더 많은 것이 있다고 확신하고 일부 단점 중 일부는 여기에 언급되지 않은 작업을 수행했습니다).

1. 더 탐색 가능합니다. 대부분의 요청의 경우 브라우저 만 사용할 수 있지만 리소스 헤더 구현에는보다 프로그래밍 방식이 테스트에 대한 접근 방식이 필요합니다. 그러나 예를 들어 모든 HTTP 요청이 탐색 가능하지는 않기 때문에 요청 이후에 REST 클라이언트 플러그인을 사용해야합니다. 우편 집배원 또는 발. Uri Pro/헤더 사기

2. uriversioned API를 사용하면 리소스 식별 및 리소스의 표현이 함께 중단됩니다. 이것은 휴식의 기본 원칙을 위반합니다. 하나의 리소스는 하나의 엔드 포인트만으로 식별해야합니다. 이와 관련하여 리소스 헤더 버전 설정 선택은보다 학문적으로 이상적입니다. 헤더 프로/우리 콘.

3. URI Versioned API는 클라이언트 개발자에게 오류가 적고 더 친숙합니다. URL의 버전 작성을 통해 개발자는 서비스 버전을 한눈에 파악할 수 있습니다. f 클라이언트 개발자는 헤더에 리소스 버전을 포함하는 것을 잊어 버리므로 최신 버전 (버전을 증가시 오류를 유발할 수 있음) 또는 301 (영구적으로 이동) 오류로 지정되어야하는지 결정해야합니다. 어느 쪽이든 더 많은 초보자 고객 개발자에게 더 많은 혼란이 있습니다. Uri Pro/헤더 사기
4. URI 버전싱은 동일한 응용 프로그램에서 여러 버전을 호출해야합니다. 이 경우 프레임 워크를 더욱 발전시킬 필요가 없습니다. 참고 :이 작업을 수행하면 디렉토리 구조에는 V2 디렉토리에 상당한 양의 중복 코드가 포함될 수 있습니다. 또한 업데이트를 배포하려면 시스템 재시작이 필요 하므로이 기술은 가능한 경우 피해야합니다. Uri Pro/헤더 사기.
5. 처음부터 버전을 염두에 두지 않은 기존 프로젝트를 위해 HTTP 헤더에 버전을 추가하는 것이 더 쉽습니다. 헤더 프로/우리 콘.
6. 에 따르면 RMM 레벨 3 휴식 원리 : 하이퍼 미디어 컨트롤, 데이터 버전을 처리하고 데이터를 설명하기 위해 HTTP 허용 및 컨텐츠 유형 헤더를 사용해야합니다. 헤더 프로/우리 콘.
7. 버전을 URL에 넣으면 클라이언트는 코드 변경 (또는 스마트 한 경우 구성)을 새 API로 조정해야합니다. 헤더 프로/우리 콘.

추가 읽기를하려는 경우 유용한 링크가 있습니다.

• Richardson 성숙 모델에 대한 Martin Fowler의 설명
• API 버전 관리 - 중추적 실험실
• Hateaos
• REST 서비스 버전에 관한 Informit.com의 기사

Answer 3

URL에서 버전을 사용하는 것이 좋습니다. 나는 이것을 잠시 동안 찾고 있었고 논의하는 다음 2 가지 자료를 발견했습니다. 편안한 API 디자인 길이.

1. 실용적인 편안한 API를 설계하기위한 모범 사례 - 헤더를 통한 URL을 통한 버전.
2. 프로그래머.stackexchange.com : REST 엔드 포인트 계획에 대한 권장 패턴은 무엇입니까?

TL; DR 답변: URL에서 버전 #을 사용하는 것은 권장되는 접근법입니다.

내가 만난 가장 잘 설계된 Apis 중 일부는- Instagram API 그리고 stackoverflow.com API - 모두이 접근 방식을 API 버전화에 사용합니다.