버전 관리 REST API. 각 API에는 자체 버전이 있습니다

URL에서, 특히 경로의 시작 부분에 다음과 같은 REST API 버전을 지정하는 것이 매우 일반적입니다.

POST /api/v1/accounts
GET /api/v1/accounts/details

그러나 버전이 각 API와 관련된 디자인은 보지 못했습니다. 즉, 각 API의 버전을 별도로 유지 관리합니다. 즉 :

POST /api/accounts/v2
GET /api/accounts/details/v3

이 접근 방식을 사용하면 변경이 필요할 때 특정 API의 API 버전을 증가 시키므로 전체 API의 버전을 증가시킬 필요가 없습니다.

일반적인 스타일 대신이 스타일을 사용하면 어떤 단점이 있습니까?

— Eng.Fouad
소스

답변:

당신이 전화를 하나의 REST API를하는 REST API의 호출 할 수있는 자원의 특정 세트 또는 자원 . REST API의 기능 으로 볼 수도 있습니다 . 모든 종류의 소프트웨어와 같이 전체 패키지는 단일 기능이나 리소스가 아닌 버전 / 업데이트됩니다.

귀하의 질문은 REST API 패키지의 리소스가 모듈 식이므로 잠재적으로 별도로 개발 및 버전 화되는 맥락에서 의미가 있습니다.

그런 다음, 내가 본 한 제안 된 리소스 로케이터 명명 규칙의 주요 단점은 다음과 같습니다.

를 들어 API 사용자 , 그것은 예측하기 적은 기억에 남는 덜 안정 훨씬 더 복잡 리소스 로케이터를 초래.
를 들어 모듈 개발자 (들) , 그것은 더 많은 작업이의 버전을 처리해야하는 지금의 자신의 리소스 로케이터.
여러 개의 모듈이 업데이트되므로 위의 단점이 기하 급수적으로 늘어남에 따라 리소스 로케이터의 변경이 훨씬 더 빈번해집니다.

API를 빌드 할 때 주요 목표 중 하나는 사용하기 쉽다는 것입니다.

HTTP 헤더를 사용하여 주요 변경 사항을 도입하거나 REST API를 버전 화하는 더 좋은 방법을 찾을 수 있습니까?

HTTP 헤더 접근 방식에 대해 조금 더 알고 싶다면 아래의 다른 답변을 참조하십시오 : https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— ClemC
소스

보다 나은 접근 방법은 다음과 같습니다. 콘텐츠 협상 을 사용 하여 Content-Type및 Accept헤더로 API 버전을 지정하십시오 .

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

다른 버전을 얻으려면의 다른 콘텐츠 유형으로 요청하십시오 Accept. 이런 방식으로 서버가 지원하는 특정 버전은 URL 구조와 완전히 독립적입니다. 동일한 서버는 Accept헤더 를 기반으로 응답 할 버전을 선택하여 여러 버전을 지원할 수 있습니다 . 또는 다른 버전에 대해 서로 다른 배포를 사용하려는 경우 Accept헤더 를 기반으로 요청을 전달할 버전을 선택하는 다른 버전의 서비스 앞에 프록시를 배치 할 수 있습니다.

또한 동일한 엔드 포인트에서 서로 다른 시맨틱 (서로 다른 버전이 아닌)으로 새로운 형식을 지원할 수 있습니다 . 예를 들어, 계정 목록 을 게시하면 /api/accounts일괄 생성을 의미 할 수 있으므로 별도의 API 끝점을 구축 할 필요가 없습니다.

— 잭
소스

omg 수락 헤더는 버전 시그널링에서 최악의 선택이어야합니다. 가능한 경우 버전 헤더를 사용하고, 필요한 경우 URL 경로 (예 : AWS 라우팅)

— Ewan

@ 이완 왜? 사용자 정의 버전 헤더는 중개자에게 컨텐츠가 다를 수 있음을 알리지 않고 다른 버전이 동일한 자원임을 나타냅니다. 캐싱 프록시는 헤더를 사용하여 v2 요청에 v1 캐시 응답을 제공하지 않습니다.

— Jack

API 요청에 대해 no-cache를 아직 사용하지 않는 경우, 가변 응답 헤더를 사용하십시오. 콘텐츠 유형은 이미 의미가 있습니다. 개인 용도로 분류하면 소비자의 삶이 어려워집니다

— Ewan

@Ewan 타입 의 vnd부분과 +구문은 다음 과 같습니다 application/json. 타입의 벤더별 하위 유형임을 나타냅니다 . 이것이 바로 컨텐츠 유형을위한 것입니다. 리소스는 여러 형식으로 제공됩니다. 클라이언트에게 원하는 형식을 선택하도록 요청하고 있습니다. 또한 API 요청이 표준 HTTP 캐싱 시맨틱을 사용할 수없는 이유는 없습니다.

— Jack

myapi v2에서 버그를 수정하면 새로운 MIME 유형이 반환되지 않습니다.

— Ewan

핵심은 각 엔드 포인트를 개별적으로 버전 화하는 경우 각 엔드 포인트를 개별적으로 배치 할 수 있어야한다는 것입니다.

모든 엔드 포인트가 동일한 코드베이스에 있으므로 공유 종속성이 있으며 함께 배치되므로 API는 일반적으로 하나의 버전을 갖습니다.

"아, 내가 변경 한 내용이 영향을 미치지 않을 것"이라 변경을 할 때 버전을 업데이트하지 않으면 실수를 할 때 문제가 생길 수 있습니다.

또한 v1과 v2의 API를 동시에 배포해야합니다. 일반적으로 각 버전을 별도의 서버에 배포하고 그에 따라 트래픽을 라우팅하면됩니다.

단일 API 버전이없는 경우 훨씬 복잡해집니다.

— 이완
소스