Tip of the Iceberg

The most common architecture used today to provide an API to cloud-based applications is known as REST. This term is shorthand for "REpresentational State Transfer". This is simply a fancy way of stating that this architecture allows an application to define how it can be instructed by a consumer of its data to manipulate the state of specific portions of that data. REST is a natural choice for such data interfaces, because it is already fundamental to how the entire Internet currently functions.

When you access nearly any website, your browser is sending what is known as a "GET" request to the server that hosts the site, which tells the server what information you are requesting. The server attempts to associate that request with resources that it can deliver. If the attempt is successful it sends back a representation of those resources; otherwise it sends back information about the error that was encountered. Similarly, when you submit data to a website – for example, searching for specific content – your browser sends a "POST" request, which transmits the information you are submitting to the server, which in turn attempts to send back information pertaining to the result of the submission. We are all familiar by now with this process, of course, even if we are unaware of the specifics of the protocol.

In addition to GET and POST requests, browsers and servers typically understand several other methods: these include (among others) PUT and DELETE. While most web applications now use GET and POST requests to allow the browser to instruct the server to replace or remove existing resources, the PUT and DELETE requests are the remaining two request methods that make up the REST standard. To sum up, the following is a brief recap of how the REST architecture defines each request method:

GET: retrieve the current state of the designated resource

POST: create a new resource

PUT: replace the resource with a new resource, or an updated version of the existing resource

DELETE: remove the resource

Blogging applications were among the first types of Internet applications to implement the REST architecture. If we consider an individual blog article to be a specific resource within a larger application, it becomes easy to visualize how this architecture functions in a "real world" scenario:

GET: retrieve information about an article, such as its title, author, "permalink", content, categorization, and the date it was posted

POST: add a new article to the blog

PUT: update an article to correct misspellings or grammatical mistakes, or to provide an update on the topic or events originally described in the article

DELETE: remove an article from the blog

The concept of a "permalink" was initially key to the entire REST architecture, as it allowed a URI (uniform resource identifier) to uniquely distinguish one resource within an application from all others. As convention dictates that the address of a blog article should never change, it was natural that each article's permalink – its permanent address – be used as its resource identifier within the application. Hence, a typical early REST API was quite straightforward: if the application server received a GET request at the address matching an existing permalink, it would send back information about the corresponding article; a PUT or DELETE request to the same address would, respectively, update or remove the article. The API would also define a base address, where a POST request would create a new article and a GET would retrieve a list of all resources, with a URI for each – to which additional requests could be sent to retrieve or manipulate a specific resource.

As more and more applications have embraced the REST approach, many have adopted a slight variation upon the original design to account for certain complexities that may not fit the model previously described. Rather than accept requests at a separate address for each resource, each address identifies an action to be performed, and the application gleans from any request additional information (such as request headers or query string parameters) to identify what resources are created or impacted by the request and, in some cases, to further refine what operation is to be performed against those resources.

Still other applications define a single address for the entire API, relying entirely on request headers and parameters to determine what data is involved and what is being done with that data. Many do not even make use of PUT or DELETE requests, allowing all supported operations to be performed via GET or POST, as nearly all websites now do. While some argue that an API must treat these four request methods in precisely the way previously described to be a "true" REST API, there is no "right" way to do this; no official standard exists. For the present, however, the underlying principles of the REST architecture form the dominant model currently being used to define the API for widely adopted Internet applications.

So why is REST important? In short, because it allows your application to take on a life of its own. Twitter is perhaps the best example of this phenomenon in active use today. It does almost nothing. It's essentially just "reverse SMS": instead of sending a short message to one person, you're sending it to whomever happens to be listening, and it allows you to choose who to listen to. That's it. That's all it does. Or, at least, that's all it did when it first arrived. Replies, "retweets", and all other current uses of the service emerged only as users started turning the service into what they wanted it to be. While it is possible that this would still have happened organically if Twitter only had one official web interface, the viral adoption that allowed such patterns to develop into behavioral memes started only after a myriad of third-party applications began to consume the application's API. Conversely, it is quite possible that if Twitter were only an API, and had no official front-end of its own, it might still have grown to the levels of usage it currently enjoys simply because enough third-party applications sprang up to appeal to every conceivable category of end user.

By offering such an API – which allows your application to be defined not by a visual interface you designed, but by the abstract concepts that its data represents – you leave the potential that each service you provide represents open to interpretation by an unlimited number of external entities. Having been given access to a specific set of functions that your service supports, a developer with whom you've perhaps had no direct interaction may identify a use for your service that you never originally intended. The result of this, of course, may not always be a net positive. If, however, the concepts your API unleashes to third-party interpretation allow people to do something they value in ways that no other service can match, you may soon witness other developers making your application ubiquitous for you in ways that literally change the world.

Before we move on, there is one crucial facet of this architecture that must be addressed: as you may have noticed, we have not yet discussed the format of the data being transported between a consumer of a REST API and the server hosting that API. This is because the REST architecture does not define a data format – only the protocol used to transport the data: namely, HTTP requests. Originally, every implementation of REST used XML. Today, JSON has become as widely used as – if not more than – XML, primarily because it is, quite frankly, simpler. Not only can languages such as JavaScript and PHP parse JSON with a single native function call into an object structure that is easier to interact with than traditional DOM/SAX parsers, but JSON simply allows the same information to be conveyed in less bytes. In order to cater to developers who prefer either format, however, many API services choose to support both formats, typically allowing developers to specify in request headers or parameters which format should be used. What is important to remember, however, is that, as the API provider, the data format is entirely up to you: you can use CSV, VCF, even a format of your own definition, if you prefer... again, REST defines the way that the data is sent, not what that data looks like. Our code examples will use JSON, but you should use whatever format(s) you feel will best accomplish your goals, such as ease of consumption or application response time.