The pursuit of APIness (part 2)

Last week we looked at web forms and we observed what was happening under the hood in terms of requests and data transferred; as an example, we tried to emulate a specific web form through a PHP script which sent a request to the web server and parsed the result to extract relevant information. The conclusion was: it’s possible, but it’s not clean. This week we’ll see how transparent automation can be.

Part 2: XML rocks

An Application Programming Interface is a predefined set of procedures for a program to use another one. On the Internet, an API will make it possible for a computer to use another one. Contrary to the hackers’ method previously explained, web APIs are meant to be officially supported by the webapp owners through extensive documentation and support. Your script will no longer try to imitate the human’s way with variables names and action URL but will rather take his own path to get data from the server.

Web APIs mostly rely on XML, which makes it possible to transfer structured data over the web. Basically, instead of sending raw POST variables to the server and receiving HTML, your request will send and receive clean and unchanging XML data.

At first, there is no limit to imagining and designing an API. Based on the example in part 1, we could imagine the following kind of request and response:

POST /submit HTTP/1.1
Host: api.community.com
Content-Length: 105
Content-Type: application/text-xml

<?xml version="1.0" encoding="UTF-8"?>
  <data>
    <name>Joe</name>
    <city>Indianapolis</city>
    <age>23</age>
  </data>

Note: it is quite common to design the API so that requests are sent to a subdomain like api.community.com instead of www.community.com. This way, requests at subdomain www are supposed to be sent by human beings and trigger HTML responses whereas requests at subdomain api are supposed to be sent by computers and trigger XML responses. Also note that I removed the .php extension from the submit page: through the API, we’re not really accessing a page but rather a resource.

HTTP/1.1 200 OK
Date: Tue, 17 Jun 2008 20:24:00 GMT
Content-Length: 85
Content-Type: application/text-xml

<?xml version="1.0" encoding="UTF-8"?>
  <data>
    <name>Anna</name>
    <name>Lisa</name>
  </data>

Programmatically speaking, coding the request in PHP is possible using cURL and parsing the response would certainly be easier using SimpleXML (included in PHP5). Therefore, implementing the above API call in PHP would look like this:

<?php

   // STEP 1: SEND THE REQUEST
   $url = 'http://api.community.com/submit';
   $header = array('Content-type: application/text-xml');
   $xml = '<?xml version="1.0" encoding="UTF-8"?><data><name>Joe</name>
           <city>Indianapolis</city><age>23</age</data>';
   $handle = curl_init();
   curl_setopt($handle, CURLOPT_URL, $url);
   curl_setopt($handle, CURLOPT_HTTPHEADER, $header);
   curl_setopt($handle, CURLOPT_POSTFIELDS, $xml);
   curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
   $response = curl_exec($handle);
   curl_close($handle);

   // STEP 2: PARSE THE RESULT AND DISPLAY THE NAMES
   $result = new SimpleXMLElement($response);
   $val = array();
   foreach ($result->name as $name) {
      $val[] = (string) $name;
   }
   print_r($values);

?>

Note: in this cURL script I had to specify the Content-type header so that our request could be correctly interpreted by the server. I could have used a few more options such as CURLOPT_TIMEOUT for example.

Using an API is better than forcing a web form for 3 reasons:

• the request goes through a special path designed for computers which is clearly defined at subdomain api.community.com
• the response data is better structured and easier to parse than a raw HTML page
• XML responses being provided for machines, the developers at community.com must commit on keeping a constant XML format: this means, for example, that they can’t suddenly stop accepting <city> tags in the requests or change <name> tags for <person> tags in the responses (otherwise it would spread a terrible mess in 3rd party applications leveraging their API)

The last reason is well summed up in Google’s Joshua Bloch’s famous keynote on API design:

Public APIs are forever - one chance to get it right.

In the example above, we have assumed that community.com developers had created their API from scratch, inventing a custom XML structure for requests and responses. When it comes to designing the API, the reality is that developers tend to respect some existing API structures specifically designed for APIs in order to make their API easier to learn and use for 3rd party developers.

Today, 3 API standards are widely used on the web:

• REST (REpresentational State Transfer)
• XML-RPC (XML Remote Procedure Call)
• SOAP (Simple Object Access Protocol)

Next week we’ll have a look at these three XML standards with detailed examples of how to send and receive data.

(go to Part 3: Let’s take a REST)