求求你们，千万别再说自己是REST了

REST 谁能详细讲讲呢？

Please try to adhere to them or choose some other buzzword for your API.

Roy, what do you think is the reason that so many people who think they are doing REST get it wrong?

Hi BillHiggins:

To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST. Likewise, I suspect a lot of people get it wrong because they read only the Wikipedia entry on the subject, which is not based on authoritative sources.

However, I think most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. As architectural styles go, REST is very simple.

REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release. There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).

And, of course, lately there has been a lot of “me too” activity around REST, as is the nature of any software buzzword.

So two questions I’ve always had about this constraint (if you’d be so kind to answer). I apologize if they are dumb, but they are questions I have.

1) What if the set of resources you want to expose is “flat”? Can you not have a RESTful service if there aren’t hyperlinks because the resources don’t naturally have them?

2) When you do have resources that are “like the web” - except for Atom/AtomPub - most resources aren’t as standard as HTML. So when you talk about automated agents aren’t those agents coupled to the particular service they know how to use and traverse?

Hi jonflanders:

1) Any important resource in a RESTful system must have an identifier, so I don’t see how you could have a set of resources (greater than one) which is “flat”. There are a lot of systems that have flat storage, like database records, but that’s exactly the kind of back-end implementation decision that REST is trying to hide. Sometimes an interface has to do work in order to avoid client coupling to the implementation.

2) Automated agents are dependent on their understanding of the media types, link types, or microformat extensions provided in representations. It is the same basic issue as with human communication: we will always need a common vocabulary to make sense of it. Exposing that vocabulary in the representations makes it easy to learn and be adopted by others. Some of it will be standardized, some of it will be domain-specific, but ultimately the agents will have to be adaptable to new vocabulary.

I had a hard time with the writing in this article; I don’t normally perform exegesis on blog posts. Am I interpreting this correctly?

1. Behavior should be determined by media types. For example, the operations you can perform on an image are predetermined by the fact that it’s an image. I *assume* this bears some relation to GET/POST/PUT/DELETE and how these should be interpreted for various media types… The definition of GET/POST/PUT/DELETE is formal (e.g. “safe”, “idempotent”) as opposed to semantic (they don’t mean CRUD). So, presumably GET/POST/PUT/DELETE are given meaning by the media type.

2. The interface to operations should be discovered. The example of html forms suggests that by e.g. GETting an image we know what parameters can be passed back (e.g., ?width=x&height=y to perform a resize, etc.). This reminds me of the service discovery in XMPP.

3. The location (URI) of objects in the system should have indirection in that by getting a root resource it has links to child resources. We shouldn’t know the location of child resources in advance (e.g., as it might be specified in an API doc).

So let me ask about the motivation for these design suggestions. Suppose I were designing a social networking site, where I have a person with many photos, favorite books, etc. You would advise to not explicitly layout a URL scheme beforehand (e.g., /people/1, /people/1/photos, /people/1/books), but to discover this with hyperlinks by traversing starting at / (slash). If I were looking at /person/1 I would know what the various hyperlinks point to given that I know in advance the media type representing a person (some xml format, say).

So with this example, I don’t really see what I’ve accomplished. I still have the out-of-band specification / coupling in that the media type needs to be specified in advance. The hyperlinks don’t seem to profit much by the price of indirection since I need to know what kind of media type I would get at each URL and I only know this if I know the media type of the parent resource in advance. The price of this indirection is, of course, an unnecessarily chatty protocol. The interface discovery of form elements doesn’t offer much, because although you’ve decoupled the query string format from the out-of-band protocol, in order to interpret the form (e.g., to know what “width” means), I need to know the media type in advance. The only advantage of this approach, it seems to me, is that by the interface and uri decoupling you’ve made the api resilient to protocol changes (e.g., you can move away from HTTP)–but this, to me, seems of little value.

Dr. Fielding, can you please clarify. And be gentle with jargon please.

Hi nkallen:

I’m not sure that I can clarify much in a blog comment, but I will try to answer the main points of confusion.

1) Every media type defines a default processing model. For example, HTML defines a rendering process for hypertext and the browser behavior around each element. It has no relation to the resource methods GET/PUT/POST/DELETE/… other than the fact that some media type elements will define a process model that goes like “anchor elements with an href attribute create a hypertext link that, when selected, invokes a retrieval request (GET) on the URI corresponding to the CDATA-encoded href attribute.” Identifiers, methods, and media types are orthogonal concerns — methods are not given meaning by the media type. Instead, the media type tells the client either what method to use (e.g., anchor implies GET) or how to determine the method to use (e.g., form element says to look in method attribute). The client should already know what the methods mean (they are universal) and how to dereference a URI.

2) The interface doesn’t need to be discovered. It is defined right there in the hypertext. The representation tells the client how to compose all transitions to the next application state. This could be as simple as an anchor or as complex as a java applet. For example, Day’s CQ5 content management system allows the user to perform direct image masking and manipulation on the client side and save the filtered image view as a new resource, all within the environment of a standard Web browser window.

3) The purpose of resource modeling is to figure out what resources you have that are worth identifying, representing, and manipulating. You should not be building clients that are dependent on the resource naming structure. There is simply no need to do so — the hypertext sends the client directly to the desired application state.

Thanks for clarifying my confusion. More or less, I think you’ve confirmed the essence of my interpretation. I want to ask again: what are the merits of an architectural style like this?

The argument you use is that out-of-band specification overly couples the client to the server. Hypertext mitigates this. But since the media type specifies, a priori, the kind of state transitions that can be performed, the coupling and out-of-band communication have happened in a RESTful world too. (Note that I’m thinking of an agent as opposed to a person). Given that this is the case, I don’t see the value in providing a hypertext document locating the various transition URIs, since it provides indirection to no end.

The only value the hypertext indirection provies where there are collections of resources of a certain kind and you want to discover what they are (e.g., you want to know the current list of favorite books so you go to /favorites/books and that points you to /favorites/books/the-pleasure-of-hating.html). Still, you must know the kinds of resources (the media types in advance). I would guess, though, that this is such a trivial use of hypertext that you can find few APIs that–falsely, in your view–claim to be RESTful but don’t have this feature.

Hi nkallen,

I don’t see how disagreeing with everything you wrote could be interpreted as “confirmed the essence of my interpretation.” Perhaps my comment 20 (above) will help clarify the role of standards in RESTful systems.

Roy, maybe I’m misinterpreting your corrections then. You said

1. “the media type tells the client either what method to use”; I interpret this to mean that the media type defines the state transitions and the media type specifies which methods map on to which state transitions. This is essentially are more precise statement of my original interpretation, is it not?

2. “The interface doesn’t need to be discovered. It is defined right there in the hypertext.” This is, again, a matter of semantic precision. The state transitions are known a priori; the resouces on which you can perform the transitions are linked to.

3. Again, you’re restating my interpretation: the resource naming (uris) should not be specified in advance, but linked to.

I still feel your answers to jdubray in #20 are unsatisfactory. The out of band communication is happening when defining the media type. The only argument you marshall for media types in stead of fixed resources is that the media types can be shared across sites. That has value, but it’s a pretty weak value.

nkallen,

The media type identifies a specification that defines how a representation is to be processed. That is out-of-band information (all communication is dependent on some prior knowledge). What you are missing is that each representation contains the specific instructions for interfacing with a given service, provided in-band. The media type is a generic processing model that every agent can learn if there aren’t too many of them (hence the need for standards). The representation is specific to the application being performed by the agent. Each representation therefore provides the transitions that are available at that point in the application.

When representations are provided in hypertext form with typed relations (using microformats of HTML, RDF in N3 or XML, or even SVG), then automated agents can traverse these applications almost as well as any human. There are plenty of examples in the linked data communities. More important to me is that the same design reflects good human-Web design, and thus we can design the protocols to support both machine and human-driven applications by following the same architectural style.