REST – Universal Identifier

Finally, REST architecture relies on resource identifiers that are: unique, unambiguous, universal across the system and universally accessible regardless of context. Put more simply, identifiers should provide a way to access a resource from anywhere in a consistent fashion as long as the resource is available.

These identifiers are typically URIs, URLs, and URNs. URIs (Uniform Resource Identifiers) can be classified as locators (URLs [Uniform Resource Locators]), as names (URNs [Uniform Resource Names]), or as both. A URN functions like the scientific names given to plants, animals, and compounds. A URL provides an address like those used to identify homes, businesses and websites. Stated concisely: the URN defines an item’s unique identity, while the URL provides a method for finding it.

Note that REST does not require the identifier to be human readable. The ASN.1 OID is as valid as the latin name Candida Albicans for describing a unique object or resource. However, since systems are built, used and maintained primarily by people, many RESTful systems devote a significant amount of time to crafting readable resource identifiers.  For example, Instagram uses a hierarchy in crafting readable URLs for their API. Retrieving the photos you have liked is accomplished by calling  users/self/media/liked using Instagram’s public API. In short: resources should be easily and uniquely referenced via resource identifier’s that may or may not be easy to decipher.

REST – Mapping Behavior to Implementation

A key concept in a REST architecture is a mapping between behaviors and the implementation. The best known way to this is mapping HTTP methods to resource behaviors.  The applicable HTTP methods are GET, PUT, POST, DELETE, and HEAD.  I will not be discussing the TRACE and CONNECT methods in this post.  GET, PUT and HEAD are idempotent methods, meaning the result of the method (state of the resource) will be the same regardless of when, where or how many times they are called on a particular resource.  Idempotency allows among other things the caching of responses, increasing the efficiency of the application or system.

GET is the HTTP method we are most familiar with, it is essentially the surfboard used to surf the web.  GET returns the representation of the resource requested.  In the case of the web, GET returns HTML pages, CSS style sheets, JavaScript scripts and variety of media (sounds, music, pictures, video, etc . . .).

PUT sends an entire resource representation to the server or peer to create or update a resource.  The resource representation must be sent in it’s entirety because the resource cannot be updated in parts or portions because of PUT’s idempotency.

POST is the second most popular HTTP method, POST is used frequently in AJAX calls, form submissions and anything else imaginable.  POST is a processing directive for the resource referred to in the URI/URL to handle, as such, the server or peer may handle the POST in any they define.  POST is often used to update a resource, create a resource, call another HTTP method that’s not supported by the client or trigger some other processing on the server/client.

HEAD is identical to GET except it does not return the resource, rather it returns the existence and size of the resource that would be returned by a GET request.

DELETE requests the deletion of the resource found at the URI/URL address.

The idempotency and cacheability of GET, HEAD, and PUT allow for robust, efficient, and scaleable systems.  The immense power and flexibility POST allow enumerable systems and applications in every domain to live on the internet.

REST – Resource Representation

At it’s heart REST, hypermedia and therefore HATEOS revolve around linking and managing resources.  Resources like nouns represent persons, places, things, concepts,  states, or qualities.  A resource is an available asset, representation of real-world entities, or a source of supply, support, or aid.  Though REST does not define what resource representations should look like, they should be easy to understand, parse and manipulate.

JavaScript Object Notation (JSON) is one popular format for data representation and transmission.  JSON is a simple and flexible system that compactly represents data as name-value pairs.  JSON is widely known for it’s readability, ease of use and ubiquity. JSON is most often found as the way JavaScript stores data in web applications.

Extensible Markup Language (XML) is another extremely common way to represent data.  XML is quite powerful because it allows for the creation of sophisticated structures in the data representation.  XML is crafted with a combination of open, closing and self-closing tags, tag attributes and of course the contents of the tags.   XML is readable, quite verbose (reducing it’s compactness), and like JSON is both easy to use and ubiquitous. The Extensible Hypertext Markup Language (XHTML) is the Hypertext Markup Language (HTML) that conforms to the conventions and guidelines of well-form XML in order to enjoy XML’s advantages.

Although the resource representation chosen is not significant to REST, there MUST be a resource representation to transfer state between clients, servers, and peers in an architecture built on REST.  Resource representations should be well thought out, consistent, easy to modify and most importantly tailored to the problem they are used to solve.


HATEOAS (Hypermedia As The Engine Of Application State)

Links between resources drive the state of peers, clients and servers. These hyperlinks provide transitions between the states of a given resource. Each resource representation has at least one link to another resource, thus creating hypermedia. Clients learn the state of a resource and it’s relationship to other resources through it’s resource representation.   This is the principle that enables HTTP and HTML to weave the World Wide Web.  A browsers points to a web page (resource),  the server responds with the page, the browser then reads the page and requests all the images, scripts, style sheets, and pages referenced in frames and iframes (resources).  Finally, the browser renders the page using each resource where it’s needed.  The rendered page often contains numerous links to other pages or files (resources). This structure allows people to surf the web on the waves of hypermedia.