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.