是REST API真的RPC？ 罗伊菲尔丁似乎认为如此 是REST API真的RPC？ 罗伊菲

A large amount of what I thought I knew about REST is apparently wrong - and I'm not alone. This question has a long lead-in, but it seems to be necessary because the information is a bit scattered. The actual question comes at the end if you're already familiar with this topic.

From the first paragraph of Roy Fielding's REST APIs must be hypertext-driven, it's pretty clear he believes his work is being widely misinterpreted:

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

Fielding goes on to list several attributes of a REST API. Some of them seem to go against both common practice and common advice on SO and other forums. For example:

• A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). ...

• A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). ...

• A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. ...

The idea of "hypertext" plays a central role - much more so than URI structure or what HTTP verbs mean. "Hypertext" is defined in one of the comments:

When I [Fielding] say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction.

Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.

I'm guessing at this point, but the first two points above seem to suggest that API documentation for a Foo resource that looks like the following leads to tight coupling between client and server and has no place in a RESTful system.

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

Instead, an agent should be forced to discover the URIs for all Foos by, for example, issuing a GET request against /foos. (Those URIs may turn out to follow the pattern above, but that's beside the point.) The response uses a media type that is capable of conveying how to access each item and what can be done with it, giving rise to the third point above. For this reason, API documentation should focus on explaining how to interpret the hypertext contained in the response.

Furthermore, every time a URI to a Foo resource is requested, the response contains all of the information needed for an agent to discover how to proceed by, for example, accessing associated and parent resources through their URIs, or by taking action after the creation/deletion of a resource.

The key to the entire system is that the response consists of hypertext contained in a media type that itself conveys to the agent options for proceeding. It's not unlike the way a browser works for humans.

But this is just my best guess at this particular moment.

Fielding posted a follow-up in which he responded to criticism that his discussion was too abstract, lacking in examples, and jargon-rich:

Others will try to decipher what I have written in ways that are more direct or applicable to some practical concern of today. I probably won’t, because I am too busy grappling with the next topic, preparing for a conference, writing another standard, traveling to some distant place, or just doing the little things that let me feel I have I earned my paycheck.

So, two simple questions for the REST experts out there with a practical mindset: how do you interpret what Fielding is saying and how do you put it into practice when documenting/implementing REST APIs?

Edit: this question is an example of how hard it can be to learn something if you don't have a name for what you're talking about. The name in this case is "Hypermedia as the Engine of Application State" (HATEOAS).

Answer 1:

我觉得你的解释大多将其覆盖。 URI是应该，在大多数情况下，不会告知超出所使用的用户代理来访问应用程序的书签URI不透明标识符。

至于文档化，这个问题已经做了好几次。 您记录您的媒体类型，再加上超链接控制，它包含（链接和表单），以及交互模型，如果你愿意的话（见的AtomPub）。

如果文档中的URI或如何建立他们，你就错了。

Answer 2:

你的解释似乎是正确的我。 我相信，Fielding的约束可以实际应用。

我真的想看到有人发布的如何记录一个REST接口，一些很好的例子。 有这么多不好的例子，有一些有效的人将用户指向将是非常有价值的。

Answer 3:

我一直在寻找继HATEOAS编写API的一个很好的例子，并已经很难找到一个（我发现无论是SunCloud API和AtomPub的东西很难申请到“正常” API的情况）。 所以，我试图使我的博客上意味着什么，是一个正确的REST实现跟着罗伊Fieldings建议一个现实的例子。 我发现它来非常困难了的例子，尽管这在原则上是相当简单的（以相对于网页中的API时只是混淆）。 我得到了罗伊正在与问题，并同意，它只是一个思想转变到正常实施的API。

看一看： API示例使用REST

Answer 4:

的一个例外关于如何建立的URI给出指令是，它允许将在超文本响应发送URI模板，与字段被自动由客户端使用在超文本等领域取代。 这通常不会挽救了多少带宽，虽然，因为gzip压缩会处理URI的不够好，不与本打扰的重复部分。

关于REST和相关HATEOAS一些很好的讨论：

优势（也）使用HATEOAS在RESTful API中

如何获得一杯咖啡

Answer 5:

对于那些有兴趣，我发现在实践中HATEOAS的详细示例Sun云API 。

Answer 6:

大多数人得到错误的事情是，（至少我认为）在REST世界里，你不记录您的“REST接口”，您记录的是一个媒体类型，您的服务器或服务的独立。

Answer 7:

完全正确。 我想除了注意的是URI模板是一个RESTful应用程序中完全正常，只要模式是从服务器接收（OpenSearch的是一个合适的例子）文件。 对于URI模板，您记录他们正在使用的地点和模板的预期占位符是什么，而不是模板本身。 略相反的是Wahnfrieden说，这是不是一个例外。

例如，在我的工作中，我们有一个内部的域管理系统，并在服务文档指定了两个URI模板：构建一个URI查询域名可用性的一个用于生产的最佳猜测URI的域资源，而另一个。 它仍然可以通过域集合页找出给定域的URI的，但由于它管理，这不会是客户端可行域的数量巨大，所以给他们一个办法猜测是什么域资源可能是URI是从方便客户的角度实施，并从服务器的带宽方面的一个巨大的胜利。

在你的问题：我们的规范性文件暴露的资源，对这些资源的各种方法中的代表性媒体类型的影响，以及它们的模式，什么样的资源在这些representions中的URI指向。

我们也已经连接到它免责声明不要过多解读该文件，这使典型的客户机 - 服务器交互的例子中提到的URI的非规范（资料）的文档。 这使相当抽象的规范性文件中的具体条款。

Answer 8:

我认为在这REST一直在那里，现在的年数，技术人员都来了资源的概念，真正是或不是RESTful的条款。

据理查森成熟度模型中，有4个级别（0-3），定义你的API如何RESTful的是，有3含义的真正的RESTful API，就像罗伊菲尔丁预期的那样。

0级是当你有一个入口点URI - 如SOAP。

等级1表示该API可以不同资源之间进行区分，并且拥有超过一个切入点 - 仍然气味SOAP的。

2级是当您使用HTTP动词 - GET，POST，DELETE为主。 这是在该REST真正进入画面的水平。

在第3级，你开始使用超媒体的控制，让您真正的API基于REST的。

进一步阅读建议链接：

• 什么是理查德森成熟度模型？
• Martin Fowler的博客：理查德森成熟度模型

Answer 9:

假设GET /foos/createForm被调用，以获得其当我们去创造，必须提供表单字段值POST /foos 。 现在，即1此特定的URL用于创建的Foo应该在响应中提到GET /foos/createForm为根据Fielding的主张提交操作环节，对不对？
那么什么是映射操作的众所周知的HTTP动词来操作的好处，“约定优于代码/配置”的事情被废止。

文章来源: Is That REST API Really RPC? Roy Fielding Seems to Think So