Web APIs Basics

An Application Programming Interface is a predefined set of procedures for a computer program to interact with another one. Operating systems (such as Linux or Windows) provide APIs so that software programs can fit into the existing environment and, for example, use the file system, display a standard user interface or make use of dialog boxes. Libraries are pure APIs: an image manipulation library makes it possible for a computer program to programmatically manipulate images through predefined functions. To a certain extent, VBA can be considered as an API too: through Microsoft Excel's VBA, two worksheets can interact with each other and find/edit/compute data.

Websites have evolved from static HTML pages to complex and dynamic database-backed online applications. Take Knol for instance: it's not a simple brochuware website, it's a full web application designed to explain, share, moderate and cross-link information, on which you can add and edit text, comment pages, parameterize settings, etc. The same way APIs establish bridges between software programs, web APIs build connections between web applications.

Transmission over HTTP

Communication between web applications occurs through HTTP (Hypertext Transfer Protocol). The same way a human user requests a webpage through a URL, a software program can request structured data by calling a specific URL.

Here is a simple schema to better understand what happens when a web browser requests a specific URL (here http://example.com/users to get the users of fictitious website http://example.com):


Upon requesting the webpage, the browser receives HTML code which, once processed, is displayed to the end-user. The characteristic of HTML is that it contains both data and presentation: when the browser receives, say <span class="member" style="color:#000">Member: Mr Jones</span>, it receives both data ("Mr Jones is a user of http://example.com") and presentation (here: display "Mr Jones" in black font and apply the CSS styles for "member" elements).

What computer programs need is pure data, i.e. data without presentation. In the previous example, the data was mixed with presentation. Here is what a computer program would like to receive when requesting the users of http://example.com:


Now the script can easily parse the information retrieved from the server (in this example, we've used XML but we could have used JSON as well).

In this example, we've imagined that the script simply wanted to retrieve a list of users. Say we now want a script aimed a getting information on a specific profile: when requesting the data, the profile's ID needs to be stated. There are two ways of doing so:

1. stating the ID in the URL (see schema 1 below)
   
2. POSTing the ID within the request (see schema 2 below)

Here is a schema for method 1:


And here is a schema for method 2:

REST, XML-RPC and SOAP

So far, we've seen that web APIs consisted mainly in XML messaging over HTTP. There is some flexibility in how to design the messaging system, how to design the URLs, how to design the XML snippets to be sent and received etc. It is now time to introduce the 3 buzzwords orbitting nearby the "web API" meme.

REST is a set of software architecture principles based on: