<aside> 📝 Work in Progress: This page is still a rough draft.

</aside>

REST is good! It is also very commonly misunderstood; most APIs and API systems are not truly RESTful.

What REST really means

Roy Fielding formulated REST for “software design on the scale of decades”. While REST has seen widespread adoption as a buzzword, Dr. Fielding has lamented that many APIs that claim to be RESTful really are not. Straight from the horse’s mouth (emphasis added):

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). […] 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. Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard.

<aside> 🧠 More notes and discussion from the above-mentioned post can be found at Fielding REST post.

</aside>

When I first started this project, I was under the impression that, since I believe in HATEOAS as a principle and intend to encourage it more strictly, Veneto is upholding REST principles. Dr. Fielding’s post directly confronted me with the truth that REST truly exists on a separate time scale; it exists to solve different problems.

In the comments, Dr. Fielding further elaborates:

October 21, 2008 at 4:45 am

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 using them]. 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.

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.

October 21, 2008 at 6:18 am

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.

My interpretation of that

<aside> 🤷🏽 This section is just my opinion based on what I currently know and understand. I’ve attempted to get in touch with Dr. Fielding to hear more of his thoughts, and I’ll update this page if he ever gets back to me.

</aside>

It seems to me that in essence, Dr. Fielding is describing modern web apps. In fact, it’s hard to imagine something adhering to those constraints that fits my understanding of an API. To me, an API is something you use to create an application by accessing data and functionality from elsewhere; the API consumer might modify the content presented by the server to suit its use case. The methodology set forth by Dr. Fielding is indeed extremely resilient to change over time, as was its original purpose, but it is not flexible from the perspective of the API consumer. I see three options:

• A web “API” which is essentially an application in its own right, serving some sort of a user interface, like HTML and web forms, that contains the entire representation of the resource and the means of manipulating it (along with relevant links). Its status as an API might only imply that it is consumable by a third party in a particular context. In any case, its only option is to display exactly all of the content the API serves it; no more and no less.
• A hypothetical user-facing “generic” REST client that operates on raw data rather than a formatted user interface, which may indeed already exist, that similarly is limited to rendering exactly what the server sends it
• An application that consumes a REST API, manipulates and extracts data and functionality based only on commonly-understood semantics, and is then able to customize the output to suit its needs.
  This is somewhat possible now with HTML and/or XML, but is not yet practical for most use cases. The set of use cases for API consumption is far too broad to be covered by the current state of HTML and the like, which I believe is the motivating force behind the development of modern web applications. It’s important to realize that REST is very explicitly protocol- and language-agnostic. The principles Dr. Fielding outlined can be applied to any other media, and the limitations posed by HTML with respect to modern application use cases could be solved. If a solution currently exists, I haven’t heard of it.

To do anything else, the API consumer needs to statically understand what it’s receiving and what it can send. When an API has a documented interface, that does represent a coupling of the client and the server, and therefore is a hazard to longevity - but it frees the consumer of any restrictions on what it might be able to do; the client can do anything the server lets it. This is a fundamental trade-off, and I believe documenting it and proposing solutions was Dr. Fielding’s purpose in his dissertation.

Everyone knows this to some degree or another, which is why the temptation to couple the client and server is so alluring. Much to Dr. Fielding’s chagrin, REST has simply become a catchall buzzword for any data-based web API, but that usage betrays its actual principles.