30 Mar 2013
REST API concepts

Every now and then I bump into these terms, and it’s not easy to grasp the definitions in a blink of an eye. It’s not easy because, while REST models real life concepts in a simple manner, we are not accustomed to so much semantics in daily programming. Everything is mostly data, text, a class, an instance, an object, etc. This post is mainly a note-to-self, but hopefully it has a good-enough analogy that you can use as well.

Some things might be off, and there might surely are better analogies, so I’d be happy if you leave a comment and set me straight. disclaimer

My analogy has some tight coupling with the HyperREST API icons that I patched together a couple of weeks ago. The Font Awesome icons came in like a glove.






Entity m:n Resource

An entity may be your invoice (the concept, not the paper) for electricity for 2013 Mar 1-31st. The resource, on the other hand, holds your latest invoice. So the same resource, this inbox that you access every month, will link to some magical/undefined concept that is behind the curtains of the electrical company, that we refer to as the invoice.

If you’re stuck thinking in terms of URIs, here goes. There’s https://example.com/invoices/{id} and then there’s https://example.com/invoices/latest. Behind the curtains there’s a DB, and there’s a table called Invoices with a primary key id. While the https://example.com/invoices/{id} resource may have at times a 1:1 relation to the DB’s Invoices#{id} record, the resource that is identified by https://example.com/invoices/latest will not - it will link to a different entity, based on a variety of factors like the current timestamp, or the Authorization header, while maintaining its definition intact “the latest invoice”.

The same entity can be used by multiple resources,
and the same resource can use multiple entities.
Neither the former, nor the latter, identifies the other.

Resource 1:n Representation

“The latest invoice” resource can be represented by a webpage, an email message, a PDF document, a paper invoice, an electronic invoice in your online bank account, an audio invoice for the visually impaired, etc. These are all representations of the same concept, of the same resource.

The same resource can accept or provide multiple representations.
The same inbox can accept or provide multiple envelopes.
The latter does not identify the former.

Representation n:1 Content-Type

These representations come with meta descriptors, headers, to let you know how to interact with them. The Content-Type header describes the content of the representation, in terms of semantics and syntax. text/html for a webpage, application/pdf for a PDF document, audio/mp3 for audio content in MP3 format.

The content of multiple representations can be described by the same Content-Type.
The content of multiple envelopes can be described by the same cover.
The latter does not identify the former.

Representation n:1 Payload

A representation without its Content-Type is just a payload. A PDF document without a application/pdf header, or say without the .pdf file extension, is just a binary file. A sheet of paper without indicators that it is an invoice, from the electricity company, etc. is nothing more than a sheet of paper with ink on it. That sheet of paper can be the support or the medium of an invoice sometimes, or a greeting card some other times.

Representations of application/json or application/json; charset=utf-16 types may share the same payload {}. Similarly, an integer, or a textual string, or a string representing a number in base 2, or base 10, may all be equaled to 11.

Multiple representations can share the same payload.
Multiple envelopes can share the same letter.
The latter is part of the former.


( )* ~ = ( = + )*

Off-topic: Content-Type vs Media-Type

Can anyone shed some light on the differences, if any?

I tend to take Content-Type as referring to the HTTP header, and thus it can be application/json; charset=utf-8, while Media-Type refers to the {type, subtype} tuple alone, without the parameters - application/json. That’s what you see in a couple of places as well. But if you take a quick look at the HTTP grammar though, you can clearly see that’s an opinionated definition.