나머지 API 버전 전략
App Store를 통해 가져 오기 우리의 응용 프로그램 에서이 게시물을 읽으십시오!
내부 REST API 버전 관리 전략.
SO 및 Google 등을 통해 REST API를 버전 관리하기위한 몇 가지 전략을 찾았지만 내부 REST API를 버전 관리하는 데 필요한 전략을 찾지 못했습니다 (웹 개발자는이 앱을 만들려고합니다. 일반적인 REST API는 있지만 일반 사용자는 API에 액세스 할 수 없습니다.
API는 내부 용으로 만 사용되므로 이전 버전과의 호환성이 거의 필요없고 기본적으로 '현재'및 '가장자리'또는 이와 유사한 방식이 필요합니다. 최소한의 번거 로움을 피하기 위해 내부 REST API를 버전 화하는 데 필요한 간단하고 유용한 전략에 대한 정보는 훌륭합니다.
현재는 차별화하는 아주 나쁜 방법입니다. / current / users에 대한 호출을 수행하는 응용 프로그램이 있고 / current / users가 다른 정보를 반환하도록 API를 업그레이드하면 응용 프로그램이 중단됩니다.
버전 관리에 집착하십시오. 단순한 / v1 / users는 명확하고 간결하며 / v2 / users를 추가하면 이전 API 엔드 포인트를 사용하는 응용 프로그램은 계속 작동하며 필요한 경우 사용자를 업데이트 할 수 있습니다.
API 버전을 업데이트하는 방법, 2 부.
이것은 API 버전 관리의 시리즈 중 두 번째 파트입니다. 1 부에서는 API 버전 관리 및 클라이언트가 특정 버전에 대해 특정하게 코딩 할 수 있도록하는 일반적인 방법에 대해 설명했습니다. 나는 당신이 그 게시물을 읽는 것을 제안한다. (적어도 소개를 훑어 라!) 이 기사에서는 Accepts 헤더 사양에 대해 잘 모르는 몇 가지 개념을 활용하여 다른 방법으로 버전이없는 API를 만들 수 있다고 암시했다. 그러나 저는 아직까지도 여전히 중요하다고 생각합니다. 하지만 저는 여전히 그 점이 중요하다고 생각합니다. 여전히 API에서 버전을 올릴 수는 있지만 인터페이스 자체를 버전 관리하지는 않습니다. 리소스 표현을 단순히 버전을 지정하는 것입니다.
REST로 작성된 API에서 가장 일반적인 변경 사항은 자원에서 필드를 추가, 변경 또는 제거하는 것입니다. 새로운 정보가 추가되거나 다른 형식 일 수 있습니다. 정보를 사용할 수 없게 될 수도 있습니다. 자원 자체를 추가, 이동 또는 제거 할 수도 있습니다. API 아키텍처에 따라 HTTP 동사가 약간 다른 것을 의미 할 수 있습니다. 이들 모두는 기존 애플리케이션이 중단되는 경우 일반적으로 API 버전 증가가 필요합니다. 그러나 약간의 사전 고려 사항을 사용하면 전체 API 버전 관리 전략을 요구하지 않고도 API를 변경할 수 있습니다.
무차별 인터페이스 설계 :
정상적인 URI 스키마 사용 : / api / collection_name / resource_id HTTP 메소드의 정의를 따르십시오. 자원은 항상 하위 호환성을 유지해야합니다. 어쨌든 버전간에 자원을 제거해야합니다. 이동 자원은 HTTP 코드를 리디렉션하여 처리 할 수 있습니다.
버전 리소스 표현 :
Accepts 헤더를 사용하십시오. 정보를 항상 하위 버전과 호환되어야합니다. 어쨌든 버전간에 정보를 제거해야합니다. 버전 정보 허용으로 정보를 이동할 수 있습니다.
버전없는 API를 설계합니다.
먼저 버전없는 API가 이상적인 상태라는 점을 인정하고, 잘 생각한 버전 전략을 사용하는 API는 API를 사용하는 것이 좋으며, 버전을 지정하지 않으려 고하는 시도가 불충분하다고 생각하면됩니다. 버전 관리가 필요하다고 생각하는 데 부끄러운 일이 없으며 가능한 모든 API가이 버전없는 전략에 부합 할 수 있습니다. 이는 실제로 표준을 따르는 REST 기반의 리소스 조작 기반 API에서만 작동합니다. 즉, 이 스타일에 맞게 많은 API를 재 작업 할 수 있습니다. 또한이 기능은 웹 프런트 엔드와 상호 작용하는 API가 아니라 백엔드 API 용입니다. 필자는 API의 사용자에 대해 걱정하지 않고도 자신의 페이스대로 웹 프론트 엔드 기능을 업데이트 할 수 있도록 거의 항상 별도의 API를 사용해야한다고 생각합니다. 나는 개인적으로 프론트 엔드 API에 대한 표준을 따르는 데있어서 개인적으로 훨씬 더 느리다는 것을 안다.
버전없는 API를 만드는 방법을 이해하는 첫 번째 단계는 인터페이스 자체의 버전을 원하지 않는다는 것입니다. 즉, 정보를 저장하고 액세스하는 방법과 위치를 변경하지 않아도됩니다. 실용적인 측면에서 이것은 URI 구조입니다. 이 규칙조차도 구부릴 수 있습니다. 물론 HTTP 스펙에 내장 된 것은 리다이렉트입니다! 정보를 이동 한 경우 새 URI에 영구적 인 리디렉션을 제공하기 만하면됩니다. 이제 리소스를 제거하면 어떻게됩니까?
일반 API에서 특정 URI를 제거 할 수있는 두 가지 이유는 다음과 같습니다. 리소스 유형 자체가 제거되었거나 더 일반적으로 리소스의 특정 표현이 더 이상 지원되지 않습니다. 후자의 경우 REST 아키텍처를 실제로 따르지 않는다. 자원 표현은 URI에서 분리되어야한다. 전자의 경우 전체 리소스 유형에 더 이상 액세스 할 수없는 경우 비즈니스 이유로 인해 이전 버전의 API에서 모두 제거하려고합니다. 이 경우 버전 관리는 실제로 당신에게 아무 것도주지 못했습니까?
리소스 또는 정보를 리소스에 추가하는 작업은 항상 이전 버전과의 호환성이 있어야합니다. JSON을 사용하는 경우 기존 리소스에 요소를 추가하는 것은 간단합니다. XML 스키마가있는 경우에도 정의 된 스키마에이를 추가하고 스키마의 자체 복사본을 다운로드 한 클라이언트에게 경고를 보내어 업데이트 할 수 있습니다. 완전히 새로운 리소스를 추가하려면 간단히 추가하십시오! 아무도 영향을받지 않아야합니다.
아마도 무언가를 만들 수있는 가장 어려운 일은 특정 API에서 특정 메소드를 수행 할 때 일어나는 일에 대한 변경 사항 일 것입니다. 예를 들어, 이전에 / api / foo /에 POST 할 수 있었고 새로운 foo 리소스를 만들었지 만 이제는 기존 foo 리소스를 편집하려고합니다. 내가 말할 수있는 최선의 방법은 권장되는 HTTP 사양 메서드 정의를 명시 적으로 따르는 것입니다.
POST / api / foo / 또는 GET / api / foo / 또는 GET / api / foo / 1은 자원 또는 자원 콜렉션을 검색하며 멱등수입니다 (동일한 결과로 반복 가능) POST / api / foo /는 새로운 자원을 작성하며 멱등하지 않습니다 (반복하면 자원이 많이 생성됩니다). PUT / PATCH / api / foo / 1 (제안 된 표준)은 특정 리소스의 필드를 업데이트하고 멱등 (idempotent)입니다. DELETE / api / foo / 1은 리소스 (때로는 리소스 모음)를 삭제합니다. 멱등수이다.
기술적으로 DELETE는 리소스가 처음에는 존재하지 않았고 올바른 방법으로 오류가 발생하더라도 오류가 발생한다고 알려야한다고 생각합니다. 그러나이를 보류합니다. OPTIONS와 HEAD는 덜 사용되며, 사용한다면 어쨌든 당신이하는 일을 알고있을 것입니다. PATCH를 사용하는 경우 잘 지원되는 표준이 아니므로 많은 API가 불완전한 PUT 요청을 수락하고 변경된 필드 만 업데이트합니다. 필자는 적어도 널리 받아 들여질 때까지 여드름 패치 지원이 잘되어 있고 문서화 된 동작을하는 한 이것이 괜찮다고 생각합니다.
많은 경우 POST 요청에 따라 리소스가 수정됩니다. 양식을 제출하면 데이터를 해석하고 자원을 변경합니다. 이는 프런트 엔드 API에서 흔히 볼 수있는 패턴입니다. 위에서 언급했듯이 그 점이 좋습니다. 완벽하지는 않지만 괜찮습니다. 백엔드 API에서 이것은 발생하지 않아야합니다! PUT 또는 PATCH 요청을 사용하고 새 자원을 원하는대로 명시 적으로 정의하십시오. 일반적인 구절은 IE의 이전 버전이 PUT 또는 PATCH를 지원하지 않지만 백엔드 API이므로 괜찮습니다! 필자가 알고있는 모든 주요 라이브러리는 PUT을 지원합니다 - 사용하지 않는 라이브러리를 사용한다면 아마도 다른 곳에서보아야합니다.
간단히 말해서, 무결점에 대한 전제 조건은 리소스에 대한 URI, HTTP 메서드 및 리소스 자체를 나타내는 데이터 만 있으면서도 모든 리소스가 일관된 방식으로 액세스 및 조작 될 수 있어야한다는 것입니다. 여러 URI에서 단일 논리 자원 (예 : 사용자 프로파일)을 조작하는 경우 버전을 사용해야하는 상황이 발생할 가능성이 큽니다.
리소스 표현의 버전 관리.
소개에서 언급했듯이 클라이언트에 전송 된 리소스 표현 자체는 버전 관리되어야 할 수 있습니다. 이 접근 방식의 장점은 각 리소스를 독립적으로 버전을 관리 할 수 있다는 것입니다. 하나의 리소스를 변경 한 다음 한 달 후에 다른 리소스를 변경하기로 결정하면 API 버전 카운터를 두 번 증가시켜야합니다. 각 자원 버전은 개별적으로 증가합니다. 리소스 자체의 버전을 지정하는 것이 아니라 리소스를 나타내는 것입니다. 버전이있는 리소스 (예 : 사용 가능한 이전 버전이있는 문서)는 여기에 설명 된 방법과 별도로 액세스해야합니다.
Accept 헤더 스펙에 익숙해지면 스펙이 앞으로 어떻게 될지에 대한 진정한 깊이를 이해하는 데 도움이 될 것입니다. 거의 모든 사람들은 Accepts 헤더가 application / json과 같은 요청자가 기대하는 MIME-Type의 종류를 지정한다는 것을 알고 있습니다. 하나의 유형을 지정할 수있을뿐만 아니라 여러 유형의 허용 가능한 유형과 각 유형의 매개 변수를 지정할 수 있음을 알고 있습니다. 리소스 표현을 버전 화하기 위해 형식 매개 변수를 활용할 것입니다.
나는 다음과 같은 점을 고려해야한다.
Accepts 헤더를 완전히 이해하지 못했을지라도이 문자열은 json 형식의 application / vnd. example. foo 형식, 사용 가능한 경우 버전 2 및 그 밖의 버전을 예상한다는 것을 암시 할 수 있습니다. specs와 일치하는 방식으로 Accepts 헤더를 파싱하는 것은 많은 라이브러리가 상자에서 파싱하지 않기 때문에 어려울 수 있습니다.
그렇다면 자원 표현을 언제 버전화해야합니까? 위에서 언급했듯이 리소스에 대한 정보를 제거하면 더 이상 리소스를 노출시키지 않아도되는 비즈니스 이유 때문일 수 있습니다. 오늘날 압축 전송 시대에는 정보가 더 이상 유용하지 않다고 단순히 말하면서 정보를 제거 할 수 없게됩니다. 정보를 추가하는 것은 항상 하위 호환 가능 방식으로 수행 할 수 있어야합니다. 필드의 이름 및 / 또는 유형을 변경하는 경우에 버전을 지정하고 싶을 수 있습니다. 예를 들어 (실제 실례의 시간!) 필드에 & # 8220; 활성화 됨 & # 8221; 보다 일반적인 & # 8221; 상태로 & # 8221; enum 유형.
자, 어떻게해야합니까?
불행하게도, 여기에서 논의한 많은 것들은 실제로 널리 사용되는 API를 실제로 구축하는 사람들의 커뮤니티에서 거의 지원하지 않습니다. 나는 이것의 작은 부분이 현실 세계의 응용 프로그램에서 이들을 구현하는 데 어려움이 있다고 생각하지 않습니다. 플랫폼에 따라 쉽거나 어려울 수 있으며이 라이브러리와 같은 버전 관리 전략을 지원하는 라이브러리는 거의 없습니다. Accepts-version 헤더에 기반한 버전 화 된 라우팅을 지원하는 node-restify가 가장 가까운 것으로 알고 있습니다.
몇 가지 라이브러리를 통해 향후 버전 관리를 지원하도록 라이브러리를 확장하려고 시도 할 것입니다. 아마도 이걸 많이 무료로 구할 수있는 내 자신의 라이브러리를 시도했을 것입니다. 개발자가 표준을 준수하는 코드를 작성하는 것이 더 쉬울수록 더 쉽게 채택 할 수 있습니다. 왜냐하면 결국 개발의 용이성과 표준 준수가 내려지기 때문에 항상 매번 쉽게 이길 것이라는 것을 알고 있기 때문입니다 .
나머지 API 버전 전략
App Store를 통해 가져 오기 우리의 응용 프로그램 에서이 게시물을 읽으십시오!
API 버전 관리 모범 사례? [닫은]
웹 서비스 REST API 버전 관리를위한 알려진 방법 또는 모범 사례가 있습니까?
나는 AWS가 엔드 포인트의 URL에 의한 버전 관리를한다는 것을 알았다. 이것이 유일한 방법입니까 아니면 같은 목표를 성취 할 수있는 다른 방법이 있습니까? 여러 가지 방법이 있다면 각 방법의 장점은 무엇입니까?
templatetypedef, amon, George Stocker & # 9830;에 의해 주로 의견 기반으로 마감되었습니다. 3 월 6 일 14시 13 분 22 초
많은 좋은 질문은 전문가의 경험을 토대로 어느 정도 의견을 제시하지만, 이 질문에 대한 답변은 사실, 참고 문헌 또는 특정 전문 지식보다는 의견에 거의 근거를 두는 경향이 있습니다. 이 질문을 도움말 센터의 규칙에 맞게 수정하려면 질문을 수정하십시오.
animuson 님에 의해 잠김 & # 9830; 3 월 8 일 16시 3시 40 분.
이 질문은 역사적인 의미가 있기 때문에 존재하지만이 사이트에 대한 주제에 관한 좋은 질문으로 간주되지 않으므로 여기에서 비슷한 질문을 할 수있는 증거로 사용하지 마십시오. 이 질문과 답변은 고정되어 있으며 변경할 수 없습니다. 추가 정보 : 도움말 센터.
이것은 좋고 까다로운 질문입니다. URI 디자인의 주제는 동시에 REST API의 가장 중요한 부분이며, 따라서 해당 API 사용자에 대한 잠재적 인 장기적 약속입니다.
응용 프로그램의 진화와 그보다 낮은 수준의 API는 삶의 사실이며 프로그래밍 언어와 같이 겉으로보기에는 복잡한 제품의 진화와 유사하기 때문에 URI 디자인은 자연적인 제약이 적어야하며 보존해야합니다. 시간이 지남에. 응용 프로그램과 API의 수명이 길어질수록 응용 프로그램과 API의 사용자에 대한 책임이 커집니다.
반면에, 또 다른 삶의 사실은 API를 통해 소비 될 모든 자원과 측면을 예측하기 어렵다는 것입니다. 다행히 Apocalypse까지 사용할 전체 API를 설계 할 필요는 없습니다. 모든 자원 및 자원 인스턴스의 모든 자원 끝점과 주소 체계를 올바르게 정의하면 충분합니다.
시간이 지남에 따라 각 특정 리소스에 새로운 리소스와 새로운 특성을 추가해야 할 수도 있습니다. 하지만 API 사용자가 특정 리소스에 액세스하기 위해 따르는 방법은 리소스 주소 지정 체계가 공개되고 최종적으로 변경되지 않아야합니다.
이 방법은 HTTP verb 의미론 (예 : PUT은 항상 업데이트 / 대체해야 함) 및 이전 API 버전에서 지원되는 HTTP 상태 코드에 적용됩니다 (사용자 개입없이 작업 한 API 클라이언트가 계속 작동 할 수 있어야 함). 그런 식으로).
또한 API 버전을 URI에 포함 시키면 시간이 지남에 따라 변할 리소스 주소 / URI가 있으므로 응용 프로그램 상태 엔진 (Roy T. Fieldings PhD 논문에서 언급 한)의 하이퍼 미디어 개념이 중단되므로 API 버전은 API 사용자가 의존 할 수있는 리소스 URI가 퍼머 링크가되어야 함을 의미하는 오랜 시간 동안 리소스 URI에 보관되어서는 안됩니다.
물론 기본 URI에 API 버전을 포함 할 수는 있지만 새 API 버전에서 작동하는 API 클라이언트를 디버깅하는 것과 같이 합리적이고 제한된 용도로만 사용할 수 있습니다. 이러한 버전이있는 API는 시간 제한적이어야하며 폐쇄 된 베타와 같이 제한된 API 사용자 그룹 만 사용할 수 있습니다. 그렇지 않으면, 당신은 당신이하지 말아야 할 곳을 저 지르게됩니다.
만료 날짜가있는 API 버전 유지에 관한 몇 가지 생각. 웹 서비스 (Java, PHP, Perl, Rails 등)를 구현하는 데 일반적으로 사용되는 모든 프로그래밍 플랫폼 / 언어는 웹 서비스 종점을 기본 URI에 쉽게 바인딩 할 수 있도록합니다. 이렇게하면 여러 API 버전간에 파일 / 클래스 / 메소드 모음을 쉽게 수집하고 보관할 수 있습니다.
API 사용자 인 POV에서 특정 API 버전으로 작업하고 바인딩하는 것이 더 쉬울뿐만 아니라 제한된 시간 동안 (즉 개발 중에) 분명합니다.
API 관리자의 POV에서, (소스 코드) 버전 관리의 가장 작은 단위로 주로 파일에서 작동하는 소스 제어 시스템을 사용하여 다른 API 버전을 병렬로 유지하는 것이 더 쉽습니다.
그러나 API 버전이 URI에 명확하게 표시되어 있으면주의해야합니다. URI 기록에서 API 기록이 가시적으로 보이고 aparent가되므로 REST의 지침에 위배되는 시간이 지남에 따라 변경되기 쉽습니다. 나는 동의한다!
이러한 합리적인 반대를 피하는 방법은 버전없는 API 기본 URI로 최신 API 버전을 구현하는 것입니다. 이 경우 API 클라이언트 개발자는 다음 중 하나를 선택할 수 있습니다.
최신 API에 맞서 개발하십시오 (잘못 설계된 API 클라이언트를 깨뜨릴 수있는 API 변경을 막기 위해 응용 프로그램을 유지 관리해야 함).
제한된 시간 동안 만 API의 특정 버전에 바인딩됩니다 (명백 해짐).
예를 들어 API v3.0이 최신 API 버전 인 경우 다음 2 개는 별칭이어야합니다 (즉 모든 API 요청과 동일하게 작동해야 함).
또한 이전 API를 가리키는 API 클라이언트는 사용중인 API 버전이 더 이상 지원되지 않거나 더 이상 지원되지 않는 경우 최신 API 버전을 사용하도록 알려야합니다. 따라서 다음과 같은 쓸모없는 URI에 액세스하십시오.
Location URI 헤더와 함께 사용되는 리디렉션을 나타내는 30x HTTP 상태 코드 중 하나를 반환해야합니다. 이 상태 코드는 리소스 URI의 해당 버전으로 리디렉션됩니다.
API 버전 관리 시나리오에 적합한 리디렉션 HTTP 상태 코드가 두 개 이상 있습니다.
301 요청 된 URI를 가진 자원이 다른 URI (API 버전 정보를 포함하지 않는 자원 인스턴스 퍼머 링크 여야 함)로 영구적으로 이동되었음을 나타내는 영구적으로 이동되었습니다. 이 상태 코드는 버전이 지정된 리소스 URI가 리소스 퍼머 링크로 대체되었음을 API 클라이언트에 알리지 않고 더 이상 지원되지 않는 API 버전을 나타내는 데 사용할 수 있습니다.
302 요청한 리소스가 일시적으로 다른 위치에 있지만 요청한 URI가 계속 지원 될 수 있음을 나타내는 Found입니다. 이 상태 코드는 버전없는 URI를 일시적으로 사용할 수없고 리디렉션 주소 (예 : APi 버전이 포함 된 URI를 가리키는 등)를 사용하여 요청을 반복해야하며 클라이언트가 계속 사용하도록 알리고 싶을 때 유용합니다 (예 : permalinks).
URL에 버전이 없어야합니다. 이 버전은 요청한 리소스의 "아이디어"와 아무런 관련이 없습니다. URL을 원하는 개념에 대한 경로로 생각해야합니다. 즉, 항목을 어떻게 반환 할 것인지를 결정하는 것이 아닙니다. 버전은 객체의 개념이 아니라 객체의 표현을 나타냅니다. 다른 포스터가 말했듯이 요청 헤더에 형식 (버전 포함)을 지정해야합니다.
버전이있는 URL에 대한 전체 HTTP 요청을 살펴보면 다음과 같습니다.
헤더에는 요청한 표현이 들어있는 행이 있습니다 ( "Accept : application / xml"). 바로 그 버전이 있어야합니다. 모두는 당신이 다른 형식으로 동일한 것을 원하고 클라이언트가 원하는 것을 요구할 수 있어야한다는 사실에 대해 광택을주는 것처럼 보입니다. 위의 예에서 클라이언트는 리소스의 XML 표현을 요구합니다. 실제로 원하는 표현을 나타내는 것은 아닙니다. 서버는 이론적으로 XML 인 경우 요청과 관련이없는 무언가를 반환 할 수 있으며 잘못되었다는 것을 파싱해야합니다.
더 좋은 방법은 다음과 같습니다.
더 나아가, 클라이언트가 XML이 너무 장황하다고 생각하고 대신 JSON을 원한다고 가정 해 봅시다. 다른 예제에서는 동일한 고객에 대한 새 URL을 가져야하므로 다음과 같이 끝납니다.
(또는 비슷한). 실제로 모든 HTTP 요청에는 원하는 형식이 포함됩니다.
이 방법을 사용하면 훨씬 더 자유롭게 디자인 할 수 있으며 실제로 REST의 원래 아이디어를 고수하고 있습니다. 클라이언트를 방해하지 않고 버전을 변경하거나 API가 변경되면 점진적으로 클라이언트를 변경할 수 있습니다. 표현 지원을 중지하도록 선택한 경우 HTTP 상태 코드 또는 사용자 정의 코드로 요청에 응답 할 수 있습니다. 클라이언트는 응답이 올바른 형식인지 확인하고 XML의 유효성을 검사 할 수도 있습니다.
URL에 버전을 넣는 것이 나쁜 방법을 보여주는 마지막 예가 하나 있습니다. 오브젝트 내부에 정보를 원한다고 말하면서 다양한 오브젝트를 버전 관리했다 (고객은 v3.0, 주문은 v2.0, shipto 오브젝트는 v4.2). 다음은 클라이언트에서 제공해야하는 불쾌한 URL입니다.
우리는 버전을 URL에 넣는 것이 실용적이고 유용하다는 것을 알았습니다. 그것은 당신이 한 눈에 사용하고있는 것을 쉽게 알려줍니다. 허용 된 답변에서 제안하는 바와 같이 / foo / (가장 최신 버전)의 별칭 / foo를 사용 용이성, 더 짧고 / 깨끗한 URL 등을 위해 수행합니다.
하위 호환성을 영원히 유지하는 것은 종종 비용이 많이 들거나 매우 어렵습니다. 더 이상 지원 중단 될 것이라는 점, 여기에 제안 된 것과 같은 리디렉션, 문서 및 기타 메커니즘을 사전에 알리는 것이 좋습니다.
리소스 표현의 버전 관리가 REST 접근법을 따르는 것이 더 낫다는 것에 동의합니다. 하지만 사용자 정의 MIME 유형 (또는 버전 매개 변수를 추가하는 MIME 유형)의 큰 문제점 중 하나는 HTML 및 JavaScript의 Accept 및 Content-Type 헤더에 쓸 수없는 지원입니다.
예를 들어 리소스를 만들려면 HTML5 양식에 다음 헤더를 사용하여 POST 할 수 없습니다.
이것은 HTML5 enctype 속성이 열거 형이므로 일반적인 application / x-www-formurlencoded, multipart / form-data 및 text / plain 이외의 다른 것은 유효하지 않기 때문입니다.
. HTML4에있는 모든 브라우저에서 지원되는지 확신 할 수 없습니다 (좀 더 느슨한 encytpe 속성을 갖지만 MIME 유형이 전달되었는지 여부에 대한 브라우저 구현 문제 일 것입니다)
이 때문에 나는 URI를 통해 버전을 만드는 가장 적절한 방법이 있다고 생각하지만 올바른 방법이 아니라고 생각합니다.
귀하의 버전을 URI에 넣으십시오. 한 버전의 API가 다른 유형의 API를 항상 지원하지는 않기 때문에 리소스가 한 버전에서 다른 버전으로 마이그레이션된다는 논쟁은 명백히 잘못되었습니다. XML에서 JSON으로 형식을 전환하는 것과 같지 않습니다. 유형이 존재하지 않거나 의미 적으로 변경되었을 수 있습니다.
버전은 리소스 주소의 일부입니다. 하나의 API에서 다른 API로 라우팅합니다. 헤더에서 주소 지정을 숨기려면 RESTful이 아닙니다.
REST API에서 버전 관리를 할 수있는 몇 가지 장소가 있습니다.
언급 한 바와 같이, URI에서. 리다이렉트 (redirect) 등이 잘 사용된다면 이는 다루기 쉽고 심미적으로 즐겁다.
Accepts : 헤더에서 버전이 파일 유형에 있도록합니다. 'mp3'vs 'mp4'처럼. 이것은 IMO가 다소 덜 능숙하게 작동하지만 작동합니다.
자원 그 자체. 많은 파일 형식에는 일반적으로 헤더에 버전 번호가 포함되어 있습니다. 이것은 새로운 소프트웨어가 파일 형식의 모든 기존 버전을 이해함으로써 '정당한 작업'을 할 수있게하며, 구 버전의 소프트웨어가 지원되지 않는 (최신) 버전이 지정된 경우 펀트 할 수 있습니다. REST API의 컨텍스트에서 URI가 변경 될 필요가 없으며 전달 된 데이터의 특정 버전에 대한 응답 만 의미합니다.
세 가지 접근법을 모두 사용해야하는 이유를 알 수 있습니다.
'깨끗한 스윕 (clean sweep)'새로운 API를 원한다면, 또는 그러한 접근 방식을 원할 경우 주요 버전을 변경하십시오. 클라이언트가 PUT / POST를 수행하기 전에 클라이언트가 알 수 있도록하려면 작동 여부를 결정해야합니다. 클라이언트가 PUT / POST를 수행하여 작동 여부를 확인해야한다면 괜찮습니다.
REST API의 버전 관리는 다른 API의 버전 관리와 유사합니다. 사소한 변경 작업을 수행 할 수 있으며 주요 변경 사항에는 완전히 새로운 API가 필요할 수 있습니다. 가장 쉬운 방법은 매번 처음부터 시작하는 것입니다. URL에 버전을 넣는 것이 가장 적합합니다. 클라이언트의 삶을 편하게하려면 역 호환성을 유지하려고 노력합니다. 영구적 인 리디렉션, 영구적 인 리디렉션, 여러 버전의 리소스 등을 통해 수행 할 수 있습니다. 이는 더 까다 롭고 많은 노력이 필요합니다. 그러나 REST가 "멋진 URI는 변경되지 않습니다"에서 권장하는 사항이기도합니다.
결국 다른 API 디자인과 같습니다. 고객의 편의를 위해 노력하십시오. API에 대한 의미있는 버전 관리를 채택하는 것이 좋습니다. 그러면 클라이언트가 새 버전과의 하위 호환성 방법을 명확하게 알 수 있습니다.
네 가지 REST API 버전 관리 전략.
이 기사에서는 네 가지 일반적인 REST API 버전 관리 전략을 설명하고 xMatters에서 REST API 버전을 어떻게 설명하는지 설명합니다.
xMatters에서 우리는 SemVer 사양 & # 8211; 주요 변경 사항을 도입 할 때마다 API 주 버전을 업데이트합니다. 내부적으로 우리는 기능 및 하위 호환 업데이트를 추가 할 때마다 마이너 및 패치 버전을 업데이트합니다. xMatters REST API의 새 주요 버전을 출시 할 때 클라이언트는 기존 주요 버전을 계속 사용하거나 새 버전으로 마이그레이션하도록 선택할 수 있습니다.
REST는 오늘날 인터넷을 통해 제 3 자에게 서비스를 제공하는 데 사용되는 가장 뛰어난 아키텍처 스타일입니다. SOAP 또는 RPC와 같은 더 복잡한 프로토콜 대신 HTTP 표준을 사용합니다. REST가 성공적으로 성공한 이유는 웹이 어떻게 작동 하는지를 모방 한 것입니다.
Stateless : 요청간에 클라이언트 컨텍스트를 유지하지 않습니다. 캐시 가능 : HTTP 캐싱 규칙을 사용합니다. 클라이언트 / 서버 지향 : 클라이언트와 서버 간의 관심사를 분리합니다. 계층화 된 시스템 및 통합 인터페이스를 활용합니다.
네 가지 일반적인 REST API 버전 관리 전략.
REST API를 버전을 지정하는 네 가지 일반적인 방법이 있습니다.
1. URI 경로를 통한 버전 관리.
REST API를 버전 화하는 한 가지 방법은 버전 번호를 URL 경로에 포함시키는 것입니다.
이 전략은 xMatters는 물론 Facebook, Twitter, Airbnb 등과 같은 다른 회사에서도 사용됩니다.
이 솔루션은 URI 라우팅을 사용하여 특정 API 버전을 가리키는 경우가 많습니다. 캐시 키 (이 경우 URI)는 버전에 따라 변경되므로 클라이언트는 쉽게 자원을 캐시 할 수 있습니다. REST API의 새 버전이 릴리스되면 캐시의 새 항목으로 인식됩니다.
API의 내부 버전은 다음과 같습니다.
주 버전 : URI에 사용 된 버전이며 API에 대한 변경 내용을 나타냅니다. 내부적으로 새 주요 버전은 새 API를 만드는 것을 의미하며 버전 번호는 올바른 호스트로 라우팅하는 데 사용됩니다.
사소한 버전 및 패치 버전 : 클라이언트에 투명하며 내부 호환 기능을 통해 이전 버전과의 호환성을 유지합니다. 일반적으로 변경 로그에서 전달되어 클라이언트에게 새로운 기능이나 버그 수정에 대해 알립니다.
이 솔루션은 급격한 변경을 도입하면 전체 API를 분기하는 것을 의미하므로 코드 기반에 상당히 큰 밑넓이가 있습니다.
2. 쿼리 매개 변수를 통한 버전 관리.
REST API를 버전 관리하는 또 다른 옵션은 버전 번호를 쿼리 매개 변수로 포함시키는 것입니다.
이것은 구현 관점에서 API를 간단히 버전 화하는 방법입니다. 또한 쿼리 매개 변수가 지정되지 않은 경우 최신 버전으로 기본 설정하는 것이 쉽습니다.
URI 버전 관리와 비교할 때 가장 큰 단점은 라우팅의 어려움입니다. 실제로 쿼리 매개 변수는 요청을 적절한 API 버전으로 라우팅하는 데 사용하기가 더 어렵습니다.
3. 사용자 정의 헤더를 통한 버전 관리.
REST API는 특성으로 포함 된 버전 번호가있는 사용자 정의 헤더를 제공하여 버전을 지정할 수도 있습니다.
이 접근 방식과 두 가지 이전 버전의 주요 차이점은 URI를 버전 정보와 함께 혼란스럽게하지 않는다는 것입니다.
4. 내용 협상을 통한 버전 관리.
curl - H & # 8220; accept : application / vnd. xm. device + json; 버전 = 1 & # 8221; example / api / products.
우리가 다루고있는 마지막 전략은 컨텐츠 협상을 통한 버전 관리입니다.
이 방법을 사용하면 전체 API를 버전 화하는 대신 단일 리소스 표현을 버전화할 수 있으므로 버전 관리를보다 세부적으로 제어 할 수 있습니다. 또한 새 버전을 만들 때 전체 응용 프로그램을 포크 할 필요가 없으므로 코드 기반에서 더 작은 공간을 만듭니다. 이 방법의 또 다른 이점은 URI 경로를 통해 버전을 지정하여 도입 된 URI 라우팅 규칙을 구현할 필요가 없다는 것입니다.
이 접근법의 단점 중 하나는 URI 버전 API보다 액세스하기가 쉽지 않다는 것입니다. 미디어 유형이있는 HTTP 헤더가 필요하면 브라우저를 사용하여 API를 테스트하고 탐색하기가 더 어려워집니다.
콘텐츠 협상은 전체 API의 버전을 지정하는 대신 리소스 표현을 버전 화하기 때문에보다 세분화 된 방식이지만 클라이언트와 개발자 모두에게 높은 구현 비용도 함께 제공됩니다. 흔히 제공하는 라이브러리가 거의 없기 때문에 콘텐츠 협상을 처음부터 구현해야합니다. 다른 접근 방식은 구현하기 쉽고 사용하기가 쉽지만 API 계약의 변경 사항을 도입하는 데 드는 높은 비용 때문에 개발자가 리팩토링 기능을 제한합니다.
어떤 생각이나 추천? 아래에 의견을 남겨주세요!
무료 백서 : 표준 + 사례에 대해 알아보십시오.
Rob England의 IT에 대한 총체적인 접근 방법에 대한 자세한 내용은 블로그 (The IT Skeptic) 및 Plus! 표준 + 사례 접근법. 자세한 내용은 정의되지 않은 사례 관리 상황을 xMatters로 작성된 새로운 표준 응답 모델로 바꾸는 방법에 대한 Rob의 새로운 백서를 읽어보십시오. Standard + Case : IT 응답 모델이 현대 운영을 주도하는 방식.
주 버전에 따라 포장 (폴더)을 만들어야합니까?
또 다른 질문은, 데이터베이스 테이블에서 API를 변경해야하는 경우 스키마의 버전을 변경하는 방법입니다. 어떤 링크?
그다지 자주 문서화되지 않은 한 가지는 코드와 API가 지원하는 모든 버전을 관리하는 방법입니다.
나는 코드를 관리하고 버전 악몽을 피하는 데 좋은 패턴을 찾기를 원했다.
spring-webmvc에 대한 제 3의 접근 방식의 구현 :
관심이있을 수도 있습니다.
AT & T, HP 및 Intel과 함께 Airbnb 환경을 해킹 한 방법
새로운 ServiceNow 통합으로 해결 시간 단축.
Moogsoft와 xMatters Integration은 새로운 수준의 인시던트 관리를 구현합니다.
좀비 작업은 방송으로 중단 될 수 없습니다.
지원이 필요하십니까?
우리의 헌신적 인 커뮤니티 사이트는 모든 xMatters 제품에 대한 도움을 얻을 수있는 최고의 장소입니다. 당사의 전문가 지원 팀과 지역 사회 사용자가 올바른 대답을 얻을 수 있도록 지원합니다.
App Store를 통해 가져 오기 우리의 응용 프로그램 에서이 게시물을 읽으십시오!
API 버전 관리 모범 사례? [닫은]
웹 서비스 REST API 버전 관리를위한 알려진 방법 또는 모범 사례가 있습니까?
나는 AWS가 엔드 포인트의 URL에 의한 버전 관리를한다는 것을 알았다. 이것이 유일한 방법입니까 아니면 같은 목표를 성취 할 수있는 다른 방법이 있습니까? 여러 가지 방법이 있다면 각 방법의 장점은 무엇입니까?
templatetypedef, amon, George Stocker & # 9830;에 의해 주로 의견 기반으로 마감되었습니다. 3 월 6 일 14시 13 분 22 초
많은 좋은 질문은 전문가의 경험을 토대로 어느 정도 의견을 제시하지만, 이 질문에 대한 답변은 사실, 참고 문헌 또는 특정 전문 지식보다는 의견에 거의 근거를 두는 경향이 있습니다. 이 질문을 도움말 센터의 규칙에 맞게 수정하려면 질문을 수정하십시오.
animuson 님에 의해 잠김 & # 9830; 3 월 8 일 16시 3시 40 분.
이 질문은 역사적인 의미가 있기 때문에 존재하지만이 사이트에 대한 주제에 관한 좋은 질문으로 간주되지 않으므로 여기에서 비슷한 질문을 할 수있는 증거로 사용하지 마십시오. 이 질문과 답변은 고정되어 있으며 변경할 수 없습니다. 추가 정보 : 도움말 센터.
이것은 좋고 까다로운 질문입니다. URI 디자인의 주제는 동시에 REST API의 가장 중요한 부분이며, 따라서 해당 API 사용자에 대한 잠재적 인 장기적 약속입니다.
응용 프로그램의 진화와 그보다 낮은 수준의 API는 삶의 사실이며 프로그래밍 언어와 같이 겉으로보기에는 복잡한 제품의 진화와 유사하기 때문에 URI 디자인은 자연적인 제약이 적어야하며 보존해야합니다. 시간이 지남에. 응용 프로그램과 API의 수명이 길어질수록 응용 프로그램과 API의 사용자에 대한 책임이 커집니다.
반면에, 또 다른 삶의 사실은 API를 통해 소비 될 모든 자원과 측면을 예측하기 어렵다는 것입니다. 다행히 Apocalypse까지 사용할 전체 API를 설계 할 필요는 없습니다. 모든 자원 및 자원 인스턴스의 모든 자원 끝점과 주소 체계를 올바르게 정의하면 충분합니다.
시간이 지남에 따라 각 특정 리소스에 새로운 리소스와 새로운 특성을 추가해야 할 수도 있습니다. 하지만 API 사용자가 특정 리소스에 액세스하기 위해 따르는 방법은 리소스 주소 지정 체계가 공개되고 최종적으로 변경되지 않아야합니다.
이 방법은 HTTP verb 의미론 (예 : PUT은 항상 업데이트 / 대체해야 함) 및 이전 API 버전에서 지원되는 HTTP 상태 코드에 적용됩니다 (사용자 개입없이 작업 한 API 클라이언트가 계속 작동 할 수 있어야 함). 그런 식으로).
또한 API 버전을 URI에 포함 시키면 시간이 지남에 따라 변할 리소스 주소 / URI가 있으므로 응용 프로그램 상태 엔진 (Roy T. Fieldings PhD 논문에서 언급 한)의 하이퍼 미디어 개념이 중단되므로 API 버전은 API 사용자가 의존 할 수있는 리소스 URI가 퍼머 링크가되어야 함을 의미하는 오랜 시간 동안 리소스 URI에 보관되어서는 안됩니다.
물론 기본 URI에 API 버전을 포함 할 수는 있지만 새 API 버전에서 작동하는 API 클라이언트를 디버깅하는 것과 같이 합리적이고 제한된 용도로만 사용할 수 있습니다. 이러한 버전이있는 API는 시간 제한적이어야하며 폐쇄 된 베타와 같이 제한된 API 사용자 그룹 만 사용할 수 있습니다. 그렇지 않으면, 당신은 당신이하지 말아야 할 곳을 저 지르게됩니다.
만료 날짜가있는 API 버전 유지에 관한 몇 가지 생각. 웹 서비스 (Java, PHP, Perl, Rails 등)를 구현하는 데 일반적으로 사용되는 모든 프로그래밍 플랫폼 / 언어는 웹 서비스 종점을 기본 URI에 쉽게 바인딩 할 수 있도록합니다. 이렇게하면 여러 API 버전간에 파일 / 클래스 / 메소드 모음을 쉽게 수집하고 보관할 수 있습니다.
API 사용자 인 POV에서 특정 API 버전으로 작업하고 바인딩하는 것이 더 쉬울뿐만 아니라 제한된 시간 동안 (즉 개발 중에) 분명합니다.
API 관리자의 POV에서, (소스 코드) 버전 관리의 가장 작은 단위로 주로 파일에서 작동하는 소스 제어 시스템을 사용하여 다른 API 버전을 병렬로 유지하는 것이 더 쉽습니다.
그러나 API 버전이 URI에 명확하게 표시되어 있으면주의해야합니다. URI 기록에서 API 기록이 가시적으로 보이고 aparent가되므로 REST의 지침에 위배되는 시간이 지남에 따라 변경되기 쉽습니다. 나는 동의한다!
이러한 합리적인 반대를 피하는 방법은 버전없는 API 기본 URI로 최신 API 버전을 구현하는 것입니다. 이 경우 API 클라이언트 개발자는 다음 중 하나를 선택할 수 있습니다.
최신 API에 맞서 개발하십시오 (잘못 설계된 API 클라이언트를 깨뜨릴 수있는 API 변경을 막기 위해 응용 프로그램을 유지 관리해야 함).
제한된 시간 동안 만 API의 특정 버전에 바인딩됩니다 (명백 해짐).
예를 들어 API v3.0이 최신 API 버전 인 경우 다음 2 개는 별칭이어야합니다 (즉 모든 API 요청과 동일하게 작동해야 함).
또한 이전 API를 가리키는 API 클라이언트는 사용중인 API 버전이 더 이상 지원되지 않거나 더 이상 지원되지 않는 경우 최신 API 버전을 사용하도록 알려야합니다. 따라서 다음과 같은 쓸모없는 URI에 액세스하십시오.
Location URI 헤더와 함께 사용되는 리디렉션을 나타내는 30x HTTP 상태 코드 중 하나를 반환해야합니다. 이 상태 코드는 리소스 URI의 해당 버전으로 리디렉션됩니다.
API 버전 관리 시나리오에 적합한 리디렉션 HTTP 상태 코드가 두 개 이상 있습니다.
301 요청 된 URI를 가진 자원이 다른 URI (API 버전 정보를 포함하지 않는 자원 인스턴스 퍼머 링크 여야 함)로 영구적으로 이동되었음을 나타내는 영구적으로 이동되었습니다. 이 상태 코드는 버전이 지정된 리소스 URI가 리소스 퍼머 링크로 대체되었음을 API 클라이언트에 알리지 않고 더 이상 지원되지 않는 API 버전을 나타내는 데 사용할 수 있습니다.
302 요청한 리소스가 일시적으로 다른 위치에 있지만 요청한 URI가 계속 지원 될 수 있음을 나타내는 Found입니다. 이 상태 코드는 버전없는 URI를 일시적으로 사용할 수없고 리디렉션 주소 (예 : APi 버전이 포함 된 URI를 가리키는 등)를 사용하여 요청을 반복해야하며 클라이언트가 계속 사용하도록 알리고 싶을 때 유용합니다 (예 : permalinks).
URL에 버전이 없어야합니다. 이 버전은 요청한 리소스의 "아이디어"와 아무런 관련이 없습니다. URL을 원하는 개념에 대한 경로로 생각해야합니다. 즉, 항목을 어떻게 반환 할 것인지를 결정하는 것이 아닙니다. 버전은 객체의 개념이 아니라 객체의 표현을 나타냅니다. 다른 포스터가 말했듯이 요청 헤더에 형식 (버전 포함)을 지정해야합니다.
버전이있는 URL에 대한 전체 HTTP 요청을 살펴보면 다음과 같습니다.
헤더에는 요청한 표현이 들어있는 행이 있습니다 ( "Accept : application / xml"). 바로 그 버전이 있어야합니다. 모두는 당신이 다른 형식으로 동일한 것을 원하고 클라이언트가 원하는 것을 요구할 수 있어야한다는 사실에 대해 광택을주는 것처럼 보입니다. 위의 예에서 클라이언트는 리소스의 XML 표현을 요구합니다. 실제로 원하는 표현을 나타내는 것은 아닙니다. 서버는 이론적으로 XML 인 경우 요청과 관련이없는 무언가를 반환 할 수 있으며 잘못되었다는 것을 파싱해야합니다.
더 좋은 방법은 다음과 같습니다.
더 나아가, 클라이언트가 XML이 너무 장황하다고 생각하고 대신 JSON을 원한다고 가정 해 봅시다. 다른 예제에서는 동일한 고객에 대한 새 URL을 가져야하므로 다음과 같이 끝납니다.
(또는 비슷한). 실제로 모든 HTTP 요청에는 원하는 형식이 포함됩니다.
이 방법을 사용하면 훨씬 더 자유롭게 디자인 할 수 있으며 실제로 REST의 원래 아이디어를 고수하고 있습니다. 클라이언트를 방해하지 않고 버전을 변경하거나 API가 변경되면 점진적으로 클라이언트를 변경할 수 있습니다. 표현 지원을 중지하도록 선택한 경우 HTTP 상태 코드 또는 사용자 정의 코드로 요청에 응답 할 수 있습니다. 클라이언트는 응답이 올바른 형식인지 확인하고 XML의 유효성을 검사 할 수도 있습니다.
URL에 버전을 넣는 것이 나쁜 방법을 보여주는 마지막 예가 하나 있습니다. 오브젝트 내부에 정보를 원한다고 말하면서 다양한 오브젝트를 버전 관리했다 (고객은 v3.0, 주문은 v2.0, shipto 오브젝트는 v4.2). 다음은 클라이언트에서 제공해야하는 불쾌한 URL입니다.
우리는 버전을 URL에 넣는 것이 실용적이고 유용하다는 것을 알았습니다. 그것은 당신이 한 눈에 사용하고있는 것을 쉽게 알려줍니다. 허용 된 답변에서 제안하는 바와 같이 / foo / (가장 최신 버전)의 별칭 / foo를 사용 용이성, 더 짧고 / 깨끗한 URL 등을 위해 수행합니다.
하위 호환성을 영원히 유지하는 것은 종종 비용이 많이 들거나 매우 어렵습니다. 더 이상 지원 중단 될 것이라는 점, 여기에 제안 된 것과 같은 리디렉션, 문서 및 기타 메커니즘을 사전에 알리는 것이 좋습니다.
리소스 표현의 버전 관리가 REST 접근법을 따르는 것이 더 낫다는 것에 동의합니다. 하지만 사용자 정의 MIME 유형 (또는 버전 매개 변수를 추가하는 MIME 유형)의 큰 문제점 중 하나는 HTML 및 JavaScript의 Accept 및 Content-Type 헤더에 쓸 수없는 지원입니다.
예를 들어 리소스를 만들려면 HTML5 양식에 다음 헤더를 사용하여 POST 할 수 없습니다.
이것은 HTML5 enctype 속성이 열거 형이므로 일반적인 application / x-www-formurlencoded, multipart / form-data 및 text / plain 이외의 다른 것은 유효하지 않기 때문입니다.
. HTML4에있는 모든 브라우저에서 지원되는지 확신 할 수 없습니다 (좀 더 느슨한 encytpe 속성을 갖지만 MIME 유형이 전달되었는지 여부에 대한 브라우저 구현 문제 일 것입니다)
이 때문에 나는 URI를 통해 버전을 만드는 가장 적절한 방법이 있다고 생각하지만 올바른 방법이 아니라고 생각합니다.
귀하의 버전을 URI에 넣으십시오. 한 버전의 API가 다른 유형의 API를 항상 지원하지는 않기 때문에 리소스가 한 버전에서 다른 버전으로 마이그레이션된다는 논쟁은 명백히 잘못되었습니다. XML에서 JSON으로 형식을 전환하는 것과 같지 않습니다. 유형이 존재하지 않거나 의미 적으로 변경되었을 수 있습니다.
버전은 리소스 주소의 일부입니다. 하나의 API에서 다른 API로 라우팅합니다. 헤더에서 주소 지정을 숨기려면 RESTful이 아닙니다.
REST API에서 버전 관리를 할 수있는 몇 가지 장소가 있습니다.
언급 한 바와 같이, URI에서. 리다이렉트 (redirect) 등이 잘 사용된다면 이는 다루기 쉽고 심미적으로 즐겁다.
Accepts : 헤더에서 버전이 파일 유형에 있도록합니다. 'mp3'vs 'mp4'처럼. 이것은 IMO가 다소 덜 능숙하게 작동하지만 작동합니다.
자원 그 자체. 많은 파일 형식에는 일반적으로 헤더에 버전 번호가 포함되어 있습니다. 이것은 새로운 소프트웨어가 파일 형식의 모든 기존 버전을 이해함으로써 '정당한 작업'을 할 수있게하며, 구 버전의 소프트웨어가 지원되지 않는 (최신) 버전이 지정된 경우 펀트 할 수 있습니다. REST API의 컨텍스트에서 URI가 변경 될 필요가 없으며 전달 된 데이터의 특정 버전에 대한 응답 만 의미합니다.
세 가지 접근법을 모두 사용해야하는 이유를 알 수 있습니다.
'깨끗한 스윕 (clean sweep)'새로운 API를 원한다면, 또는 그러한 접근 방식을 원할 경우 주요 버전을 변경하십시오. 클라이언트가 PUT / POST를 수행하기 전에 클라이언트가 알 수 있도록하려면 작동 여부를 결정해야합니다. 클라이언트가 PUT / POST를 수행하여 작동 여부를 확인해야한다면 괜찮습니다.
REST API의 버전 관리는 다른 API의 버전 관리와 유사합니다. 사소한 변경 작업을 수행 할 수 있으며 주요 변경 사항에는 완전히 새로운 API가 필요할 수 있습니다. 가장 쉬운 방법은 매번 처음부터 시작하는 것입니다. URL에 버전을 넣는 것이 가장 적합합니다. 클라이언트의 삶을 편하게하려면 역 호환성을 유지하려고 노력합니다. 영구적 인 리디렉션, 영구적 인 리디렉션, 여러 버전의 리소스 등을 통해 수행 할 수 있습니다. 이는 더 까다 롭고 많은 노력이 필요합니다. 그러나 REST가 "멋진 URI는 변경되지 않습니다"에서 권장하는 사항이기도합니다.
결국 다른 API 디자인과 같습니다. 고객의 편의를 위해 노력하십시오. API에 대한 의미있는 버전 관리를 채택하는 것이 좋습니다. 그러면 클라이언트가 새 버전과의 하위 호환성 방법을 명확하게 알 수 있습니다.
네 가지 REST API 버전 관리 전략.
이 기사에서는 네 가지 일반적인 REST API 버전 관리 전략을 설명하고 xMatters에서 REST API 버전을 어떻게 설명하는지 설명합니다.
xMatters에서 우리는 SemVer 사양 & # 8211; 주요 변경 사항을 도입 할 때마다 API 주 버전을 업데이트합니다. 내부적으로 우리는 기능 및 하위 호환 업데이트를 추가 할 때마다 마이너 및 패치 버전을 업데이트합니다. xMatters REST API의 새 주요 버전을 출시 할 때 클라이언트는 기존 주요 버전을 계속 사용하거나 새 버전으로 마이그레이션하도록 선택할 수 있습니다.
REST는 오늘날 인터넷을 통해 제 3 자에게 서비스를 제공하는 데 사용되는 가장 뛰어난 아키텍처 스타일입니다. SOAP 또는 RPC와 같은 더 복잡한 프로토콜 대신 HTTP 표준을 사용합니다. REST가 성공적으로 성공한 이유는 웹이 어떻게 작동 하는지를 모방 한 것입니다.
Stateless : 요청간에 클라이언트 컨텍스트를 유지하지 않습니다. 캐시 가능 : HTTP 캐싱 규칙을 사용합니다. 클라이언트 / 서버 지향 : 클라이언트와 서버 간의 관심사를 분리합니다. 계층화 된 시스템 및 통합 인터페이스를 활용합니다.
네 가지 일반적인 REST API 버전 관리 전략.
REST API를 버전을 지정하는 네 가지 일반적인 방법이 있습니다.
1. URI 경로를 통한 버전 관리.
REST API를 버전 화하는 한 가지 방법은 버전 번호를 URL 경로에 포함시키는 것입니다.
이 전략은 xMatters는 물론 Facebook, Twitter, Airbnb 등과 같은 다른 회사에서도 사용됩니다.
이 솔루션은 URI 라우팅을 사용하여 특정 API 버전을 가리키는 경우가 많습니다. 캐시 키 (이 경우 URI)는 버전에 따라 변경되므로 클라이언트는 쉽게 자원을 캐시 할 수 있습니다. REST API의 새 버전이 릴리스되면 캐시의 새 항목으로 인식됩니다.
API의 내부 버전은 다음과 같습니다.
주 버전 : URI에 사용 된 버전이며 API에 대한 변경 내용을 나타냅니다. 내부적으로 새 주요 버전은 새 API를 만드는 것을 의미하며 버전 번호는 올바른 호스트로 라우팅하는 데 사용됩니다.
사소한 버전 및 패치 버전 : 클라이언트에 투명하며 내부 호환 기능을 통해 이전 버전과의 호환성을 유지합니다. 일반적으로 변경 로그에서 전달되어 클라이언트에게 새로운 기능이나 버그 수정에 대해 알립니다.
이 솔루션은 급격한 변경을 도입하면 전체 API를 분기하는 것을 의미하므로 코드 기반에 상당히 큰 밑넓이가 있습니다.
2. 쿼리 매개 변수를 통한 버전 관리.
REST API를 버전 관리하는 또 다른 옵션은 버전 번호를 쿼리 매개 변수로 포함시키는 것입니다.
이것은 구현 관점에서 API를 간단히 버전 화하는 방법입니다. 또한 쿼리 매개 변수가 지정되지 않은 경우 최신 버전으로 기본 설정하는 것이 쉽습니다.
URI 버전 관리와 비교할 때 가장 큰 단점은 라우팅의 어려움입니다. 실제로 쿼리 매개 변수는 요청을 적절한 API 버전으로 라우팅하는 데 사용하기가 더 어렵습니다.
3. 사용자 정의 헤더를 통한 버전 관리.
REST API는 특성으로 포함 된 버전 번호가있는 사용자 정의 헤더를 제공하여 버전을 지정할 수도 있습니다.
이 접근 방식과 두 가지 이전 버전의 주요 차이점은 URI를 버전 정보와 함께 혼란스럽게하지 않는다는 것입니다.
4. 내용 협상을 통한 버전 관리.
curl - H & # 8220; accept : application / vnd. xm. device + json; 버전 = 1 & # 8221; example / api / products.
우리가 다루고있는 마지막 전략은 컨텐츠 협상을 통한 버전 관리입니다.
이 방법을 사용하면 전체 API를 버전 화하는 대신 단일 리소스 표현을 버전화할 수 있으므로 버전 관리를보다 세부적으로 제어 할 수 있습니다. 또한 새 버전을 만들 때 전체 응용 프로그램을 포크 할 필요가 없으므로 코드 기반에서 더 작은 공간을 만듭니다. 이 방법의 또 다른 이점은 URI 경로를 통해 버전을 지정하여 도입 된 URI 라우팅 규칙을 구현할 필요가 없다는 것입니다.
이 접근법의 단점 중 하나는 URI 버전 API보다 액세스하기가 쉽지 않다는 것입니다. 미디어 유형이있는 HTTP 헤더가 필요하면 브라우저를 사용하여 API를 테스트하고 탐색하기가 더 어려워집니다.
콘텐츠 협상은 전체 API의 버전을 지정하는 대신 리소스 표현을 버전 화하기 때문에보다 세분화 된 방식이지만 클라이언트와 개발자 모두에게 높은 구현 비용도 함께 제공됩니다. 흔히 제공하는 라이브러리가 거의 없기 때문에 콘텐츠 협상을 처음부터 구현해야합니다. 다른 접근 방식은 구현하기 쉽고 사용하기가 쉽지만 API 계약의 변경 사항을 도입하는 데 드는 높은 비용 때문에 개발자가 리팩토링 기능을 제한합니다.
어떤 생각이나 추천? 아래에 의견을 남겨주세요!
무료 백서 : 표준 + 사례에 대해 알아보십시오.
Rob England의 IT에 대한 총체적인 접근 방법에 대한 자세한 내용은 블로그 (The IT Skeptic) 및 Plus! 표준 + 사례 접근법. 자세한 내용은 정의되지 않은 사례 관리 상황을 xMatters로 작성된 새로운 표준 응답 모델로 바꾸는 방법에 대한 Rob의 새로운 백서를 읽어보십시오. Standard + Case : IT 응답 모델이 현대 운영을 주도하는 방식.
주 버전에 따라 포장 (폴더)을 만들어야합니까?
또 다른 질문은, 데이터베이스 테이블에서 API를 변경해야하는 경우 스키마의 버전을 변경하는 방법입니다. 어떤 링크?
그다지 자주 문서화되지 않은 한 가지는 코드와 API가 지원하는 모든 버전을 관리하는 방법입니다.
나는 코드를 관리하고 버전 악몽을 피하는 데 좋은 패턴을 찾기를 원했다.
spring-webmvc에 대한 제 3의 접근 방식의 구현 :
관심이있을 수도 있습니다.
AT & T, HP 및 Intel과 함께 Airbnb 환경을 해킹 한 방법
새로운 ServiceNow 통합으로 해결 시간 단축.
Moogsoft와 xMatters Integration은 새로운 수준의 인시던트 관리를 구현합니다.
좀비 작업은 방송으로 중단 될 수 없습니다.
지원이 필요하십니까?
우리의 헌신적 인 커뮤니티 사이트는 모든 xMatters 제품에 대한 도움을 얻을 수있는 최고의 장소입니다. 당사의 전문가 지원 팀과 지역 사회 사용자가 올바른 대답을 얻을 수 있도록 지원합니다.
Comments
Post a Comment