The following snippets represent little gems of knowledge in my journey of understanding RESTful architectures.

Hopefully, you’ll find them useful.

Roy Fielding

The following are clarifications that Roy has made with respect to RESTful design.

Failure to use HTTP (methods)

During the design of the Atom media type, Roy challenges the use of a link with a rel(ationship) of ‘edit‘. His point is that one only needs a resource (URL) and the HTTP verb PUT in order to support the use case i.e. editing.

Whatever happened to the idea that Atom was based on REST principles
of resources that have identifiers which a client could apply a
method to and see if that method worked by looking at the response?

Any notion of a linked resource to enable editing has fallen outside of HTTP design and hence isn’t RESTful.

Atom doesn’t need rel=”edit” or rel=”editcontent” or app:edit-content.

Note: when first investigating REST, I researched existing media types heralded as RESTful for inspiration. The learning point here is that there is a good deal of work branded as RESTful that frankly isn’t, caveat emptor.

Definition of ‘self-descriptive’

In Roy’s dissertation we learn that REST constrains messages to be ‘self-descriptive’, however, the dissertation is not very explicit about what this means. Whilst there is coverage in the use of MIME types and other HTTP headers, all of which contribute to the ‘self-descriptiveness’ I still struggled with this until I ran across this post in [rest-discuss]:

Self-descriptive means that the type is registered and
the registry points to a specification and the specification explains
how to process the data according to its intent.

So, ‘self-descriptive’ means that the exchange uses a (preferably registered) media type and that the ‘other headers’ in Section 6.3 are used appropriately.

As a counterpoint, it is worth taking a moment to consider other (non-RESTful) interpretations of self-descriptive. These are primarily schema based specifications e.g. JSON Schema, XML etc. This is not to say that such approaches are ‘bad’ (for some definition of bad) but that they use a separate layer of indirection to describe the data content. For example, the XML specification does not define the data elements of the exchange, only how to encode them, and therefore the message in not self-descriptive in the RESTful sense. To understand the message requires XML and some further (app-specific) specification of how XML is being used in that exchange.

You can of course, decide that you’re going to do things your own way:

If you only use HTTP in an APP-specific way, then all you get is one
application. If you use HTTP the way it was designed to be used,
then everyone else’s work on HTTP will be available to you. That is
what REST is all about: engineering for serendipity.