Welcome to Particletree!

Introduction

APIs are a great way to extend your application, build a community, excite your users and get in on the Mashup Mania spreading across the web. While there’s plenty out there wanting in on the action, there’s a lot of questions about how to actually go about creating an API for a web application. Like everything else technical on the web these days, there are tons of complicated and scary documents out there ready to intimidate the unprepared. In an attempt to get everyone on the bus in one piece, we’ve tried to filter through the hard stuff and give an easy to understand starting point for anyone on a quest to API’ify their web service.

An API, or Application Programming Interface, is a set of functions that one computer program makes available to other programs (or developers) so they can talk to it directly without having to give it access to the source code. The most popular APIs are from operating systems like Windows XP or Mac OS X. They allow third-party developers to write programs on top of Microsoft’s and Apple’s software. Thanks to pioneers like Amazon and eBay, the concept of APIs have to come to the web in full force and are being released by more and more web services and applications to turn their one-trick pony into platforms.

The Basics

If we type in a URL to a web site and that URL returns data in a structured format, then a basic API is already in place. For example, when you access an RSS feed, you’re essentially using an API. You type in a structured URL “asking” the server for information in RSS format and the server (usually) spits out structured data ready for your feed reader to parse.

To take this to the next level, you’ll also want to allow developers to perform actions against the data. If you want to allow someone to delete an entry from your web service, you could have them access a semantically structured URL like http://mysite.com/api/delete/. You can actually see this in practice by looking at the Backpack API.

If there’s no need to authenticate your users/developers with an API key, a GET request very well might be your method of choice and we can have the users query everything using just the URL alone. For example, selecting entry 3 from a public record could be as easy as typing in the URL: http://site.com/api/select/3.

However, when a lot of parameters need to be set (which would make the URL extremely long), or when security is of greater concern, a POST request is a safer and morecommon approach to asking data from a server. A POST request will usually require some sort of data to go along with the URL parameters so the server can check to make sure the user/developer has permission to do the type of request they’re attempting. This POST data usually contains either a password or a key to authenticate the request. You can see an example of how this is done programmatically through the Authorize.net API (Page 9 of the PDF) or through a form as seen in the Google Checkout API.

SOAP AND REST

There are two types of heavily used APIs for web services: SOAP and REST. Google is one of the major players with a SOAP based API while Yahoo (and most of their recent acquisitions) have taken the REST approach. More often than not, a “Web 2.0” service you come across today will probably be using REST.

What do these acronyms really mean? Well, there are tons of technical information and debate over the two, but here is rough breakdown as I understand it:

• REST API’s are based on HTTP, URI requests. The user of the API types in a URI, and sends data to the web service. Both the data sent, and the data returned are in formats specified by the web service. Since there are few restrictions and a small learning curve, implementing a REST API can be bit quicker and easier to understand than a SOAP API.

• A SOAP API can be thought of in the same way as REST, but its a little more structured and there’s a common format for requests and responses. Usually, services offering SOAP API’s also offer downloads that plugin into various development environments like PHP or Python. When making a request with a SOAP API, it’s more akin to a method call. For example, deleting an entry in a REST based API might be accomplished by going to http://site.com/api/delete/. With a SOAP based API, function names are available to you so it feels more like calling api->deleteEntry().

Those two basic descriptions are about as far as I will go into the topic. There are many experts advocating the use of each type, and more than enough reading to fill a semester’s worth of time. For a crash course, Myspotter offers a good starting point with a collection of links relating to both.

The rest of this tutorial covers building a REST API.

The Basics From a Code Perspective

Let’s say we have a PHP class (manage.php) that helps us manage entries in a database:

class manage {    private $entryId;    function __construct($entryId) {
        $this->entryId = $entryId;
    }    function deleteEntry() {
        //delete $this->entryId from database
    }}

On our own server, we might access this functionality like so:

require_once('manage.php');
$m = new manage(23);
$m->deleteEntry();

Easy enough for us, but how do we allow someone not on our server access to the same functionality? For that, we’ll create a third file to act as a buffer (or “interface”) between other developers and our class. Here’s an example of a file we might create to allow developers to access the delete function in our class, we’ll locate it at ‘api/delete.php’

require_once('manage.php');
if(hasPermission($_POST['api_key']) {
    $m = new manage($_POST['entry_id']);
    $m->deleteEntry();
}

This will allow users to send a POST request to us at http://site.com/api/delete.php with an api_key and an entry_id. You’ll notice the function is very similar to what we wrote on our own server except we check the POST api_key variable using a function to see if its authorized to access the database. We didn’t include that function here (hasPermission) for simplicity’s sake. In addition to what’s shown, you’d also have to find the user’s account based off of the api_key, put in some error checking and (if you want to make a good API) provide a properly formatted success or error response after the request. We’ll get into the success and error responses in a bit.

Making The Request

When building an API secured by authentication variables sent via POST, we have to understand how the data will be coming to us from the developers so we can anticipate their needs (and give them excellent examples in the documentation). With PHP, CURL is one way to do this. Building the request usually involves two steps: 1) Setting the values of the request in a key=value&key2=value2 format, and then 2) Sending the request using CURL.

Setting the parameters:

// Set the Query POST parameters
$query_vals = array(
    'api_key' => '1234-5678-9012-3456',
    'entry_id' => '3'
);// Generate the POST string
foreach($query_vals as $key => $value) {
    $ret .= $key.'='.urlencode($value).'&';
}// Chop of the trailing ampersand
$ret = rtrim($ret, '&');

The example above sets a POST variable for each parameter. Another common approach is to only have 1 POST variable, and inside that POST variable you place an XML string. Each node in that XML string would then represent a parameter. Once the POST is set, the request is then sent.

$ch = curl_init("http://site.com/api/select"); 
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);

In the examples above, the URL still dictates the action (select), but the POST contains the information needed to execute the action. Likewise, you could make a generic URL, and force the action to be in the POST. After all of that is processed, the $response variable will have structured data in it that was returned by the server.

Formatting The Response

If you’re not using a predefined format, the next step is to decide how you will format your response. Here are some things to keep in mind:

• If possible, offer both XML and JSON! Yes, this requires more work on the web service, but it gives your users a lot more flexibility to create amazing apps with your data .

• Make it easy and fast to tell if the response is an error or a success. Also, for each operation (delete, update, etc) put the success/failure notification in the same place, even though the rest of the response may be different. This is so users of your API can create a generic isSuccess() function to run every response through.

• The response should be fairly easy to understand even without looking at the documentation.

• By creating examples that use our own API, it becomes easier to see what works and what doesn’t. If a common procedure, such as drawing a table with data that comes from an API, is complicated, then it probably means the API response was harder to parse than it should be.

Below is an example REST response from the Flickr API that is both easy to read and easy to check for errors:

<rsp stat="ok">
    <method>flickr.test.echo</method>
    <format>rest</format>
    <foo>bar</foo>
    <api_key>2fdd7856207a7abb01835139403cdb45</api_key>
</rsp>

JavaScript and Security

If we’re working with server side code, API keys are fine because we can keep our key fairly protected. But what if we wanted to create a secure API accessible from JavaScript? Since JavaScript is plain text, we can’t expect someone to put their API key in there. So, we can either limit API access by domain, use Flash to aid in cross domain scripting, or just decide not to offer JavaScript access. For more information about this, Curiosity is Bliss covers the issue in detail.

If security is not an issue, a JavaScript based API will actually work out very nicely. If we host a JavaScript file, users of our API can include this file on their page, and call functions from that file. Cross Domain Ajax isn’t a problem since the file sits on our server. An example of this is the JavaScript based Yahoo Maps API.

Construction Concerns

Holy Grail

You can always add, but you can never remove.

Read about this pearl of wisdom, and more, in How to Design a Good API and Why it Matters.

From Simple to Complex

Change is always tough, and in the API world it’s even tougher. If 3 programmers are working with an internal API, it may be possible to change a function name and make the 3 programmers go through their code to change all references to that name. If an organization is using an internal API, this would be even harder to coordinate. Imagine what happens when we open up an API to anyone with an Internet connection. Forcing all references to our API to be changed will frustrate users, and create a happy helping of bugs.

So, the best way to create an API is to start easy with the basics. It may be worthwhile to just start with one operation, such as select. Once a solid request, response, and error system is worked out and tested thoroughly it is then safe to start thinking about adding more parameters and operations.

Documentation

It’s useful to provide potential users of your API with some sort of documentation describing what actions and parameters are available. Generally, this is a text document or web page detailing the API in plain writing. Another way of doing this is with WSDL:

WSDL is a document written in XML. The document describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes.

W3Schools

The painful experience of writing documentation alone should convince you to begin with simple and easy functionality. Documenting an API includes full explanation of the parameters, responses, error messages — and all of that with long working examples. If an API is constructed poorly from the beginning, all of the documentation will need to be reworked to accommodate the changes.

Conclusion

The best way to learn about APIs is to use them. After you’ve gone through the process once, the concepts become a lot easier to understand. Every web service with an API has gone through growth, user feedback and change, so there are plenty of mistakes to learn from. So get out there try out a handful of your favorite services and feel out what works for you and what doesn’t. It’s only in empathy that you’ll find inspiration to create the next great API.

Additional Reading

• How to design Good APIs and Why they Matter
• How To Design a (module) API
• Simple API Design
• ProgrammableWeb
• API Design on Fog Creek Message Board
• Create Your Own Custom API
• PostgreSQL & PHP Tutorials - Creating an API
• Part 1 of Creating a New API and Part 2