REST API가 정말 RPC입니까? Roy Fielding은 그렇게 생각하는 것 같습니다.

내가 REST에 대해 알고 있다고 생각한 많은 내용은 분명히 잘못된 것입니다. 그리고 저는 혼자가 아닙니다. 이 질문은 긴 도입부가 있지만 정보가 조금 흩어져 있기 때문에 필요한 것 같습니다. 이 주제에 이미 익숙하다면 실제 질문이 끝납니다.

Roy Fielding의 REST API 의 첫 번째 단락은 하이퍼 텍스트 기반이어야합니다. 그는 자신의 작업이 널리 잘못 해석되고 있다고 생각합니다.

HTTP 기반 인터페이스를 REST API로 호출하는 사람들의 수에 실망하고 있습니다. 오늘의 예는 SocialSite REST API 입니다. 이것이 RPC입니다. 그것은 RPC를 비명을 지른다. 디스플레이에 커플 링이 너무 많아서 X 등급을 받아야합니다.

Fielding은 REST API의 여러 속성을 나열합니다. 그들 중 일부는 SO 및 기타 포럼에 대한 일반적인 관행과 일반적인 조언 모두에 위배되는 것 같습니다. 예를 들면 :

• REST API는 초기 URI (책갈피) 및 의도 된 청중에 적합한 표준화 된 미디어 유형 집합 (즉, API를 사용할 수있는 모든 클라이언트가 이해할 것으로 예상 됨) 이외의 사전 지식없이 입력해야합니다. ...

• REST API는 고정 리소스 이름 또는 계층 (클라이언트와 서버의 명백한 결합)을 정의해서는 안됩니다. ...

• REST API는 리소스를 나타내고 애플리케이션 상태를 구동하는 데 사용되는 미디어 유형을 정의하거나 기존 표준 미디어 유형에 대한 확장 된 관계 이름 및 / 또는 하이퍼 텍스트 사용 마크 업을 정의하는 데 거의 모든 설명 작업을해야합니다. ...

"하이퍼 텍스트"라는 개념은 URI 구조 나 HTTP 동사가 의미하는 것보다 훨씬 더 중요한 역할을합니다. "하이퍼 텍스트"는 주석 중 하나에 정의됩니다.

내가 [Fielding]을 하이퍼 텍스트라고 할 때, 정보가 사용자 (또는 자동자)가 선택권을 얻고 작업을 선택하는 어포던스가되도록 정보와 제어를 동시에 표시하는 것을 의미합니다. 하이퍼 미디어는 텍스트가 미디어 스트림 내에 시간적 앵커를 포함한다는 의미의 확장 일뿐입니다. 대부분의 연구자들은 구별을 떨어 뜨 렸습니다.

하이퍼 텍스트는 브라우저에서 HTML 일 필요가 없습니다. 기계는 데이터 형식과 관계 유형을 이해할 때 링크를 따라갈 수 있습니다.

이 시점에서 추측하고 있지만 위의 처음 두 점은 다음과 같은 Foo 리소스에 대한 API 문서가 클라이언트와 서버 간의 긴밀한 결합으로 이어지고 RESTful 시스템에 자리가 없다는 것을 암시하는 것 같습니다.

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

대신 에이전트는 예를 들어 / foos에 대한 GET 요청을 발행하여 모든 Foos에 대한 URI를 검색해야합니다. (이러한 URI는 위의 패턴을 따르는 것으로 판명 될 수 있지만 요점 옆에 있습니다.) 응답은 각 항목에 액세스하는 방법과이를 통해 수행 할 수있는 작업을 전달할 수있는 미디어 유형을 사용하여 위의 세 번째 요점을 발생시킵니다. . 따라서 API 문서는 응답에 포함 된 하이퍼 텍스트를 해석하는 방법을 설명하는 데 중점을 두어야합니다.

또한 Foo 리소스에 대한 URI가 요청 될 때마다 응답에는 에이전트가 URI를 통해 연결된 상위 리소스에 액세스하거나 생성 후 조치를 취하는 등 진행 방법을 찾는 데 필요한 모든 정보가 포함됩니다. / 자원 삭제.

전체 시스템의 핵심은 응답이 진행을 위해 에이전트 옵션으로 전달되는 미디어 유형에 포함 된 하이퍼 텍스트로 구성된다는 것입니다. 브라우저가 인간을 위해 작동하는 방식과 다르지 않습니다.

그러나 이것은이 특정 순간에 나의 최선의 추측 일뿐입니다.

Fielding은 그의 토론이 너무 추상적이고 예가 부족하고 전문 용어가 풍부하다는 비판에 응답 한 후속 조치를 게시했습니다 .

다른 사람들은 내가 쓴 내용을 오늘날의 실질적인 관심사에보다 직접적이거나 적용 가능한 방식으로 해독하려고 할 것입니다. 나는 다음 주제로 씨름하거나, 회의를 준비하거나, 다른 표준을 작성하거나, 먼 곳을 여행하거나, 월급을 받았다고 느끼게하는 사소한 일을하기에 너무 바빠서 그렇게하지 않을 것입니다.

따라서 실용적인 사고 방식을 가진 REST 전문가를위한 두 가지 간단한 질문입니다. Fielding이 말하는 내용을 어떻게 해석하고 REST API를 문서화 / 구현할 때이를 어떻게 적용합니까?

편집 :이 질문은 당신이 말하는 것에 대한 이름이 없다면 무언가를 배우는 것이 얼마나 어려울 수 있는지에 대한 예입니다. 이 경우 이름은 "Hypermedia as the Engine of Application State"(HATEOAS)입니다.

나는 당신의 설명이 대부분 그것을 다루고 있다고 생각합니다. URI는 대부분의 경우 사용자 에이전트가 앱에 액세스하는 데 사용하는 책갈피 URI를 넘어서 전달되지 않아야하는 불투명 한 식별자입니다.

문서화와 관련하여이 질문은 여러 번 수행되었습니다. 포함 된 하이퍼 링크 컨트롤 (링크 및 양식)과 원하는 경우 상호 작용 모델 (AtomPub 참조)과 함께 미디어 유형을 문서화합니다.

URI 또는 ​​빌드 방법을 문서화하면 잘못된 것입니다.

당신의 해석이 맞는 것 같습니다. 필딩의 제약이 실질적으로 적용될 수 있다고 생각합니다.

누군가가 REST 인터페이스를 문서화하는 방법에 대한 몇 가지 좋은 예를 게시하는 것을보고 싶습니다. 좋지 않은 예가 너무 많고 사용자가 매우 가치가있을 수 있도록 몇 가지 유효한 예가 있습니다.

HATEOAS에 따라 작성된 API의 좋은 예를 찾고 있었는데 하나를 찾는 데 어려움이있었습니다 (SunCloud API와 AtomPub 모두 "일반적인"API 상황에 적용하기 어렵다는 것을 발견했습니다). 그래서 적절한 REST 구현이라는 것이 무엇을 의미하는지에 대한 Roy Fieldings의 조언을 따르는 제 블로그에서 현실적인 예제를 만들려고했습니다. 원칙적으로 매우 간단하다는 사실에도 불구하고 예제를 만드는 것이 매우 어려웠습니다 (웹 페이지가 아닌 API로 작업 할 때 혼란 스러움). 나는 Roy가 문제를 제기 한 것을 이해하고 동의한다. 그것은 단지 API를 위해 적절하게 구현하는 사고 방식의 변화 일 뿐이다.

보기 : Rest를 사용한 API 예제

URI를 빌드하는 방법에 대한 지침을 제공하는 한 가지 예외는 하이퍼 텍스트의 다른 필드를 사용하여 클라이언트가 자동으로 대체 할 필드를 사용하여 하이퍼 텍스트 응답에 URI 템플릿을 보낼 수 있다는 것입니다. gzip 압축이 URI의 반복 된 부분을 잘 처리하여 문제를 일으키지 않기 때문에 일반적으로 대역폭을 많이 절약하지는 않습니다.

REST 및 관련 HATEOAS에 대한 몇 가지 좋은 토론 :

RESTFul API에서 HATEOAS 사용의 장점

커피 한 잔을 얻는 방법

관심있는 사람들을 위해 Sun Cloud API 에서 실제로 HATEOAS의 자세한 예를 찾았습니다 .

대부분의 사람들이 잘못 생각하는 것은 REST 세계에서 "휴식 인터페이스"를 문서화하지 않는다는 것입니다. 문서화하는 것은 서버 또는 서비스와 관계없이 미디어 유형입니다.

REST가 현재 사용 된 수년 동안 기술자들은 리소스의 개념과 RESTful이 실제로 무엇인지 아닌지에 대해 이해하게되었습니다.

Richardson Maturity Model에 따르면, Roy Fielding이 의도 한대로 API의 RESTful 수준을 정의하는 4 가지 수준 (0-3)이 있으며 3은 진정한 RESTful API를 의미합니다.

레벨 0은 SOAP와 같은 하나의 진입 점 URI가있는 경우입니다.

레벨 1은 API가 서로 다른 리소스를 구별 할 수 있고 둘 이상의 진입 점이 있음을 의미합니다. 여전히 SOAP 냄새가납니다.

레벨 2는 주로 GET, POST, DELETE와 같은 HTTP 동사를 사용하는 경우입니다. 이것이 REST가 실제로 등장하는 수준입니다.

레벨 3에서는 하이퍼 미디어 컨트롤을 사용하여 API를 진정으로 RESTful하게 만듭니다.

추가 읽기를위한 추천 링크 :

• Richardson 성숙 모델이란 무엇입니까?
• Martin Fowler의 블로그 : Richardson 성숙 모델

절대적으로 맞습니다. 또한 URI 템플릿은 패턴이 서버에서 수신 된 문서 (OpenSearch가 적합한 예임) 인 한 RESTful 애플리케이션 내에서 완벽하게 문제가되지 않습니다. URI 템플릿의 경우 템플릿 자체가 아닌 템플릿에서 예상되는 자리 표시자가 사용되는 위치와 예상되는 자리 표시자가 무엇인지 문서화합니다. Wahnfrieden이 말한 것과 약간 반대로 이것은 예외가 아닙니다.

예를 들어, 제 작업에는 내부 도메인 관리 시스템이 있고 서비스 문서는 두 개의 URI 템플릿을 지정합니다. 하나는 도메인 리소스에 대한 최상의 추측 URI를 생성하기위한 것이고 다른 하나는 도메인 가용성을 쿼리하기위한 URI를 생성하기위한 것입니다. 주어진 도메인의 URI가 무엇인지 알아 내기 위해 도메인 컬렉션을 훑어 보는 것은 여전히 ​​가능하지만, 그것이 관리하는 도메인의 수가 엄청나게 많기 때문에 클라이언트에게는 불가능할 것입니다. 도메인 리소스의 URI는 클라이언트의 관점에서 구현의 용이성과 서버의 대역폭 측면에서 큰 이점이 될 수 있습니다.

귀하의 질문에 : 우리의 규범 문서는 노출 된 리소스, 해당 리소스에 대한 다양한 방법의 효과, 사용 된 표현 미디어 유형 및 스키마, 해당 표현의 URI가 가리키는 리소스의 종류입니다.

또한 일반적인 클라이언트-서버 상호 작용의 예를 제공하는 문서에 언급 된 URI를 너무 많이 읽지 않도록 면책 조항이 첨부 된 비표준 (정보) 문서도 포함됩니다. 이것은 다소 추상적 인 규범 문서를 구체적인 용어로 설정합니다.

GET /foos/createForm생성 할 때 제공해야하는 양식 필드 값을 가져 오기 위해를 호출 한다고 가정 해 보겠습니다 POST /foos. 이제이 특정 URL, 즉 foo를 생성하는 데 사용 된 1은 GET /foos/createFormFielding의 제안에 따라 제출 작업 링크로 응답 내에서 언급되어야합니다 .
그러면 잘 알려진 Http 동사에 대한 동작을 동작에 매핑하는 것의 이점은 무엇입니까, "코드 / 구성에 대한 관례"는 무효화됩니다.