The pursuit of APIness (part 6)

The first five posts of series “The Pursuit of APIness” went through technical examples of how APIs actually work, from an illustration of how to hack a web form with a PHP script to how to design and program an API using custom XML, or following the REST principles, or using XML-RPC or SOAP. It is now time to wrap up everything we’ve learnt about web APIs and to understand why they’re so strategic.

Part 6: Web APIs strategy

APIs are a fantastic way to make computers talk together and build great business layers on top of other business layers on top of etc. On the human side of the world, where things tend to be less binary, APIs represent a two-way strong strategic tool (”two-way” because releasing an API impacts both the original developers of a webapp and third-party developers building a third-party webapp).

Let’s start with the third-party developer’s view. In the first post of this series, we considered a fictitious dude named Joe, willing to programmatically get data out of a website called community.com (fictitious website). For him, as for any third-party webdeveloper, using an API is great because it allows to:

• backup existing data: say Joe is not confident in the future of community.com, he can programmatically backup his data stored in there through the API
• leverage existing data and, for example, display it in a more innovative way: Joe could build a great third-party application relying on community.com’s API and showing an interactive US map with the members’ names updated in real time
• catch new users: say Joe builds this app, then (at least!) a percentage of original community.com users will be interested in it and will start using it
• unload some server resources: some web services do things well and fast, so why bother reinventing the wheel and consume server resources? For example, you could save storage for your pictures by using Flickr’s API (or Amazon S3’s), you could create charts using Google’s Chart API etc.

If we look at things from community.com’s point of view, releasing an API is a strong signal and should be part of a well-thought strategy, aimed at:

• extending reach by bringing in new users from third-party apps using his/her API (there’s a mutually beneficial exchange of users between the original application and the third-party application, each one becoming a new entry point for the other)
• becoming a local expert: this is a really important point which will be analysed in the next (and last) post of this series; in a nutshell, releasing a clever API can erase competition from your niche
• fighting against web scraping: third-party webdevelopers would now have an official and documented way to get data out of an application (of course they can still keep on scraping your web pages but releasing an API greatly simplifies their lives and encourages them to keep to the straight and narrow)

API design

When releasing an API, developers should follow a comprehensive checklist to ensure third-party developers will start using it smoothly. In particular, it is essential to:

• offer the widest range of protocols: some developers love REST, so you have to release a RESTful version or your API; some other developers can’t live without XML-RPC so open a XML-RPC access to them; some other have existing libraries built for SOAP so release a SOAP API; some other love JSON so build a custom “JSON-RPC” API for them etc.
• document all the API’s functions for every protocol: yes, this is a huge work and this is were you will spend most of your time; documentation is key and the clearer it is, the more developers will use you API. Check out Flickr’s or Facebook’s APIs documentation: they’re real jowels for webdevelopers, filled with substantial code snippets helping them to get quickly started with the API.
• version your API: remember that once released, an API is forever. This means you can’t go backwards and change existing functions in your API because this would be a disaster for third-party applications built upon it and, therefore, for your users and your reputation. With an API, you can only go onwards. So it is extremely important to explicitly define versions for your API, for example by inserting version numbers right in the URL
• make it secure: web APIs have to be secure, both technically and strategically. Technically because accessing the data should happen the way it was meant to be without disrupting existing processes on the server or causing mess in the database. Strategically because releasing a web API is opening a documented door to the very heart of your content. An easy way to enhance security for your API is to release API keys: third-party developers have to request a key (usually a hash-like sequence of digits and letters) and then explicitly show this key in every single call made through the API. Doing so allows you to better monitor traffic and usage of your API.
• anticipate traffic surge: releasing an API means facing traffic spikes and, if everything goes well, facing a global increase in the load. It is crucial to anticipate this and avoid outages.

Protecting web property

Here is a simple schema to better understand what’s going on when releasing an API:

In this example, website 1 is the usual interface developed to display the data (for example: website 1 is http://community.com displaying the community.com data). Website 2 is a parallel website accessing community.com’s data but not developed by community.com. For example, it’s an aggregator designed to consolidate profiles from different online communities. For community.com, releasing a web API is interesting to extend its reach and bring in new users (for example, users of the aggregator service at website 2 who didn’t know about website 1 until they discover some of its members) but it also means organizing a documented data leak towards third-party apps, hence the need to focus on technical and strategic security.

The pursuit of APIness continues next week (last episode will be part 7). Stay tuned!

(go to Part 7: Connecting local expertises)