[rest] API 버전 관리 모범 사례? [닫은]

이것은 좋고 까다로운 질문입니다. URI 디자인 주제는 동시에 REST API의 가장 두드러진 부분 이므로 해당 API 사용자에 대한 잠재적 장기 약속 입니다.

응용 프로그램의 진화와 API의 수명 이 줄어들고 API는 프로그래밍 언어와 같이 복잡해 보이는 제품의 진화와 비슷하기 때문에 URI 디자인 에는 자연스러운 제약 이 없어야합니다. 시간이 지남에 따라 . 애플리케이션 및 API 수명이 길수록 애플리케이션 및 API 사용자에 대한 헌신이 커집니다.

반면에, 삶의 또 다른 사실은 API를 통해 소비 될 모든 자원과 그들의 측면을 예측하기 어렵다는 것입니다. 운 좋게도 Apocalypse 까지 사용될 전체 API를 디자인 할 필요는 없습니다 . 모든 자원 엔드 포인트 및 모든 자원 및 자원 인스턴스의 주소 지정 체계를 올바르게 정의하면 충분합니다.

시간이 지남에 따라 각 특정 리소스에 새로운 리소스와 새로운 속성을 추가해야 할 수도 있지만, 리소스 주소 지정 체계가 공개되어 최종적으로 API 사용자가 특정 리소스에 액세스하기 위해 따르는 방법은 변경되지 않아야합니다.

이 방법은 HTTP 동사 시맨틱 (예 : PUT은 항상 업데이트 / 교체해야 함) 및 이전 API 버전에서 지원되는 HTTP 상태 코드 (인간 개입없이 작업 한 API 클라이언트가 계속 작동 할 수 있도록 계속 작동해야 함)에 적용됩니다. 그런 식으로).

또한 API 버전을 URI에 포함하면 시간이 지남에 따라 변경되는 리소스 주소 / URI를 가짐으로써 애플리케이션 상태 엔진 (Roy T. Fieldings PhD 논문에 명시되어 있음) 으로서 하이퍼 미디어 개념이 중단되므로 API가 API 사용자가 의존 할 수 있는 자원 URI는 영구 링크이어야 함을 의미하므로 버전을 자원 URI에 오랫동안 유지해서는 안됩니다 .

물론, 기본 URI에 API 버전을 포함 할 수 있지만 새 API 버전에서 작동 하는 API 클라이언트 디버깅과 같이 합리적이고 제한된 용도로만 사용할 수 있습니다. 이러한 버전이 지정된 API는 시간 제한이 있으며 제한된 API 사용자 그룹 (예 : 비공개 베타 버전)에서만 사용할 수 있어야합니다. 그렇지 않으면, 당신은 당신이하지 말아야 자신을 저지른 다.

만료 날짜가있는 API 버전의 유지 관리에 대한 몇 가지 생각. 웹 서비스 (Java, .NET, PHP, Perl, Rails 등)를 구현하는 데 일반적으로 사용되는 모든 프로그래밍 플랫폼 / 언어를 통해 웹 서비스 엔드 포인트를 기본 URI에 쉽게 바인딩 할 수 있습니다. 이런 방식 으로 파일 / 클래스 / 메소드 모음 을 서로 다른 API 버전간에 쉽게 수집하고 보관할 수 있습니다 .

API 사용자 POV의 경우 이처럼 분명하지만 제한된 시간 동안 만 (예 : 개발 중) 특정 API 버전으로 작업하고 바인딩하는 것이 더 쉽습니다.

API 관리자의 POV에서 파일에 대해 가장 작은 단위 (소스 코드) 버전 관리로 주로 작업하는 소스 제어 시스템을 사용하여 서로 다른 API 버전을 병렬로 유지하는 것이 더 쉽습니다.

그러나 URI에 API 버전이 명확하게 표시되면주의해야 할 점이 있습니다. URI 히스토리에서 API 히스토리가 표시 / 부모 되기 때문에 시간 이 지남 에 따라 REST 지침에 위배되는 변경이 발생하기 때문에이 방법에 반대 할 수도 있습니다 . 동의한다!

이 합리적인 이의 제기를 해결하는 방법은 버전이없는 API 기본 URI에서 최신 API 버전을 구현하는 것입니다. 이 경우 API 클라이언트 개발자는 다음 중 하나를 선택할 수 있습니다.

• 최신 버전에 대비하여 개발하십시오 ( 잘못 설계된 API 클라이언트를 손상시킬 수있는 최종 API 변경으로부터 애플리케이션을 보호하기 위해 애플리케이션을 유지하기 위해 스스로 노력 ).

• 제한된 시간 동안 만 특정 버전의 API에 바인딩 (명확 해짐)

예를 들어, API v3.0이 최신 API 버전 인 경우 다음 두 개는 별명이어야합니다 (즉, 모든 API 요청과 동일하게 작동 함).

http : // shonzilla / api / customers / 1234
http : // shonzilla / api /v3.0 / customers / 1234
http : // shonzilla / api / v3 / customers / 1234

또한 사용 중인 API 버전이 더 이상 사용되지 않거나 더 이상 지원되지 않는 경우 여전히 이전 API 를 가리 키려고하는 API 클라이언트 에 최신 이전 API 버전을 사용하도록 알려야합니다 . 따라서 다음과 같이 사용되지 않는 URI에 액세스하십시오.

http : // shonzilla / api /v2.2 / customers / 1234
http : // shonzilla / api /v2.0 / customers / 1234
http : // shonzilla / api / v2 / customers / 1234
http : // shonzilla / api /v1.1 / customers / 1234
http : // shonzilla / api / v1 / customers / 1234

적절한 버전의 리소스 URI로 리디렉션되는 HTTP 헤더 와 함께 사용되는 리디렉션을 나타내는 30x HTTP 상태 코드 중 하나를 반환해야합니다 Location.

http : // shonzilla / api / customers / 1234

API 버전 관리 시나리오에 적합한 리디렉션 HTTP 상태 코드가 두 개 이상 있습니다.

• 301 요청 된 URI가있는 자원이 다른 URI (API 버전 정보를 포함하지 않는 자원 인스턴스 영구 링크 여야 함)로 영구적으로 이동했음을 나타 내기 위해 영구적으로 이동했습니다. 이 상태 코드는 사용되지 않거나 지원되지 않는 API 버전을 나타내는 데 사용되어 버전이 지정된 리소스 URI가 리소스 permalink로 대체되었음을 API 클라이언트에 알립니다 .

• 302 요청한 리소스가 일시적으로 다른 위치에 있지만 요청 된 URI가 계속 지원 될 수 있음을 나타냅니다. 이 상태 코드는 버전이없는 URI를 일시적으로 사용할 수없고 리디렉션 주소를 사용하여 요청을 반복해야하는 경우 (예 : APi 버전이 포함 된 URI를 가리키는 경우) 클라이언트에게 계속 사용하도록 요청하려고 할 때 유용합니다. 퍼머 링크).

• 다른 시나리오는 HTTP 1.1 사양의 리디렉션 3xx 장 에서 찾을 수 있습니다

답변

(BAD WAY TO DO IT):

http://company.com/api/v3.0/customer/123
====>
GET v3.0/customer/123 HTTP/1.1
Accept: application/xml

<====
HTTP/1.1 200 OK
Content-Type: application/xml
<customer version="3.0">
  <name>Neil Armstrong</name>
</customer>

(GOOD WAY TO DO IT)

http://company.com/api/customer/123
===>
GET /customer/123 HTTP/1.1
Accept: application/vnd.company.myapp.customer-v3+xml

<===
HTTP/1.1 200 OK
Content-Type: application/vnd.company.myapp-v3+xml
<customer>
  <name>Neil Armstrong</name>
</customer>

(BAD)
http://company.com/api/JSONv3.0/customers/123
  or
http://company.com/api/v3.0/customers/123?format="JSON"

(GOOD WAY TO DO IT)
===>
GET /customer/123 HTTP/1.1
Accept: application/vnd.company.myapp.customer-v3+json

<===
HTTP/1.1 200 OK
Content-Type: application/vnd.company.myapp-v3+json

{"customer":
  {"name":"Neil Armstrong"}
}

(Another reason why version in the URL sucks)
http://company.com/api/v3.0/customer/123/v2.0/orders/4321/

Accept: application/vnd.company.myapp-v3+json
Content-Type: application/vnd.company.myapp-v3+json