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:

Code snippets examples for SOAP

Characteristics of a web API

A web API can rely on one or several of the protocols and architecture designs presented above (REST, XML-RPC and SOAP), or create another protocol (JSON-RPC, custom XML etc.).

Successful web APIs require:

• a wide range of protocols: the more protocols the API offers, the more developers will be willing to use it (it is important to offer several ways to access a specific procedure: a RESTful way, a XML-RPC way, a SOAP way etc.)
• extensive documentation: an API has to be thoroughly documented, for every procedure and every protocol; documentation has to explicitly state procedures, parameters, default behaviours, error handling etc. and provide meaningful code examples for quick understanding
• security: API keys can be released in order to monitor the API usage; a successful API should not interfere with confidential information and should not mess up the data (a strong focus has to be put on data validation and error handling)
• server capacity: a successful API will dramatically increase the load; it is therefore necessary to anticipate the traffic surge and scale smoothly
• versions: once released, an API is forever; code refactoring is banned, unless it leads to releasing a new version of the API; all versions should be maintained
  

Taking these contraints into account, here is how an API could be designed for fictitious website http://example.com:

    http://api.example.com/1.0/rest/users/1234
    http://api.example.com/1.0/xmlrpc
    http://api.example.com/1.0/soap

The following characteristics make this API structure extremely powerful:

1. clear separation from the "normal website" by using a "api" subdomain
2. explicit version number in the URL
3. explicit protocol definition ("rest", "xmlrpc" etc.)

Famous examples of web APIs

Several hundreds of websites and web applications have released APIs. Here is a list of 5 famous and successful APIs:

• Flickr: website / documentation
• Facebook: website / documentation
  
• GoogleMaps: website / documentation
  
• Amazon: website / documentation
• Basecamp: website / documentation
  

The Pursuit of APIness

APIs are a great way to reach more audience, extend the user base and go beyond the boundaries of the original website or web application. Web APIs contribute in building the web as a growing ecosystem of specific services made available to any script or software program.

This Knol was written by nemetral, author of a series of posts about web APIs entitled "The Pursuit of APIness". The series can be found on his devblog at http://nemetral.net:

    The Pursuit of APIness (part 1) : The dirty way
    The Pursuit of APIness (part 2) : XML rocks
    The Pursuit of APIness (part 3) : Let's take a REST
    The Pursuit of APIness (part 4) : Review of XML-RPC
    The Pursuit of APIness (part 5) : SOAP: Hot or not?
    The Pursuit of APIness (part 6) : Web APIs strategy
    The Pursuit of APIness (part 7) : Connecting local expertises