Untangled

REST APIs…

Protocol

• need to be protocol-agnostic - essentially relying only on URIs (URI is King)
• generally should not rely on any changes to the protocol - if they do, it should be as a formalized extension, and really just to fix something that is broken

Coupling

• must not define fixed resource names or hierarchies (an obvious coupling of client and server)
  • Interestingly, Fielding allows URI templates here, even though I disagree with them. URI templates require the client to have access to the values needed to use them, which may not be statically possible and is prone to breakage
• “should spend almost all of its descriptive effort in defining the media type(s) used for representing resources”, [Failure here implies that out-of-band information is driving interaction instead of hypertext.
  • ‼️ This contradicts our current plan for static links, and feeds back into a debate I’ve been having with myself for a while. It’s a philosophical question that needs to be answered sooner than later - how much out-of-band information is acceptable and why? What about when applications need to have statically-defined schemas?
• A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names. [ditto →] Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].
  • ‼️ Same as above. When and how is this possible?

Comments

Roy T. Fielding says:

October 21, 2008 at 4:45 am

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.

Roy T. Fielding says:

October 21, 2008 at 6:18 am

HTTP operations are generic: they are allowed or not, per resource, but they are always valid. Hypertext doesn’t usually tell you all the operations allowed on any given resource; it tells you which operation to use for each potential transition. The client (user or agent) has to decide what transition to take, not what interface to use.

HTML doesn’t need type specifications. No RESTful architecture needs type specifications. Don’t expect REST to act like some other architectural style. You don’t get to decide what POST means — that is decided by the resource. Its purpose is supposed to be described in the same context in which you found the URI that you are posting to. Presumably, that context (a hypertext representation in some media type understood by your client) tells you or your agent what to expect from the POST using some combination of standard elements/relations and human-readable text. The HTTP response will tell you what happened as a result. In HTTP, a single resource-creating POST action will result in a 201 response with another hypertext representation (telling you what happened and what can be done next) or 204 response with the Location header field indicating the URI of the new resource.

Takeaways

• Maybe OpenAPI is more RESTful than I thought? At least according to Fielding. It explicitly encourages URI templating