APIs and Mashups For The Rest Of Us

Got something to say?

Share your comments on this topic with other web professionals

Published on June 4, 2007

All the latest and coolest web apps seem to have an API these days. But what is an API? And why should you care?

This article, the first in a series of two, aims to lift the lid on all things API; the second article will give you some hands-on tools and tips to get you started. For now, it’s all about how we managed to get here—and where here actually is.

What is an API?

Let’s get the acronym out of the way first. API stands for Application Programming Interface. Paraphrasing answers.com, that means it is:

…a language and message format used by an application program to communicate with a control program.

We’ll get to what that actually means a little later.

Historically, the web was all about places to visit. Consider the times when you wanted something, whether that was a specific book, some snippet of travel information, or whatever. You visited a site that you thought might have it, or that a search engine seemed to think was a good match. The web was all about what and where—what you wanted, and where you might find it.

Fast-forward to the present-day—all that is starting to change. The web is starting to become about how. The book you were looking for can now be purchased from hundreds of sites, or you might even be able to read it online or download a copy. The travel information you were looking for? You’re as likely to use a site which aggregates information from lots of providers (and takes a cut of the proceeds from the sale) as to visit the travel company directly. This is where APIs come in.

An API, in very simple terms, is the definition of what can be done programmatically with a particular application. A quick example might help to make sense of that:

Flickr, the photo-sharing site, has a pretty comprehensive API, which you can find documented at flickr.com/services/api/. Down the right hand side of that page there is a list of API methods. This is the list of what we, as programmers, can do with Flickr. If you can see past the slightly cryptic names, you’ll notice that these are the very things the Flickr user interface lets us do already, for example, list your contacts (flickr.contacts.getList), or add a tag to a photo (flickr.photos.addTags). Based on this information, we can write our own programs to add tags to all our photos on Flickr, or maybe to list all our contacts on the home page of our blog.

That leaves only one question. Why?

Why sites have APIs

By exposing the inner workings of their site or application via an API, the site provider allows the community to make of it what they will. Applications can be extended in ways that may have been impossible, uneconomical, or unimaginable for the original developers to do themselves.

For instance, the social music site last.fm has plugins for all sorts of obscure music players that most people haven’t heard of, thanks to making its API public. And it’s not just the latest Web 2.0 sites that make good use of APIs either; both Amazon and eBay have extensive developer programs based around their APIs, allowing their products to reach a much wider audience than would be possible even with two of the most popular sites on the internet.

The next obvious question is, “What does the programmer writing code against these APIs get out of this?” From the hacker’s point of view, APIs provide a great way of standing on the shoulders of giants, as well as making a service more useful for themselves and others. And if you’re really lucky, those others might even pay for your services. GetTextBooks.com, for instance, makes extensive use of the Amazon API—as well as information from a number of other book sellers—to provide a simple price comparison service that also makes them money.

So, do you like the idea of Flickr, but don’t like the web-based interface? Make your own interface and still share all your photos with your friends. Want to play with maps in an upcoming project but can’t afford to launch satellites into space to photograph the world? Use the Google Maps API and let the smart people at Google deal with the infrastructure while you solve only the problem at hand.

Amazon’s S3 service is particularly interesting in that it is only an API, in this case for simple, low-cost online file storage. Amazon doesn’t provide any user interface themselves, leaving it solely for the use of other people’s applications that need to store data such as IconBuffet and the jQuery library.

Portable open data

Another good reason to provide an API for your application is that more and more people are storing their information online in one way or another—uploading their personal photos or links to an online repository, and managing parts of their business online. Flickr, del.icio.us and Basecamp are some of the most popular. However, this movement of data online is still limited to the early adopters; people don’t like feeling locked in—after all, it’s their data which they have spent time collecting.

In a good example of acknowledging this predicament, del.icio.us and ma.gnolia.com, which offer similar services for online link management, both provide APIs. This makes it simple for people to write user-friendly tools to move data between the two. And the project management application Basecamp allows you to extract all the data you have entered into an XML file for you to walk away with. While it may not initially seem like good business sense to allow your customers to switch to a competitor so easily, consider some real-world equivalents—banks in the real world may not like people moving their accounts to another bank, but how many new accounts do you think they would open if they specifically prohibited you from doing so?

Mashups

Possibly even more interesting is the idea of mashups. According to Wikipedia, a mashup is:

…a website or application that combines content from more than one source into an integrated experience.

By taking the data that we are now able to extract from various sites via their APIs, we can plug together seemingly unconnected services into useful—or at least interesting and sometimes fun—sites and applications. Twitter plus Google Maps? See TwitterVision. Flickr meets Suduko? See FlickrSudoku. The possibilities are pretty much endless.

Creating an API for your app

If you’re building an application, or planning on doing so, you might be wondering whether a public API would be of use to anyone. This is nearly always the wrong question. By exposing a public API, you are throwing down the gauntlet to your users. Whereas before you might have had feature requests emailed in by happy (or not so happy) users, instead you can let those with the inclination and skills do the work—to the benefit of all involved. What you should be thinking about is how to encourage people to contribute their time and energy, and how you’ll reward those that do with love and traffic.

It’s worth thinking here about whether you need a formal developer network, like eBay, or whether you simply put up a few pages with the API details and see what happens. The latter is likely to involve less work, and you might find setting up a mailing list helps people get started. The former is likely to be relevant only where there is a financial incentive involved, like selling Amazon merchandise via its API through your own online store.

If you’re already sold on the idea of having an API for your site or application, then you’ll find more information about how to go about building one in the second part of this series.

Ease of Use

If you are going to be spending any length of time hacking on a specific API, you want to know that it’s going to be as painless as possible. This ease of use is also hugely important if you intend to build a community around your own application’s API. This can be looked at in two ways:

By exposing only a small amount of core functionality, and in the simplest way possible, you make it very easy for people to quickly write apps or libraries. Twitter is beautifully simple at heart, and its API mirrors this, with only a few methods available at present. This means that lots of people are able to jump straight in.
Flickr does the opposite. Flickr’s public API is simply a part of a larger API on top of which the Flickr site itself is built—the methods you can call are the same methods used by the internal developers working on Flickr. That means there are a lot of methods (one hundred at the moment in the public API), but also that they are very well documented. Without good documentation, they would not be able to continue to develop Flickr so quickly.

Microformats as an API

If you’re thinking that you’d like to be able to take advantage of some of this API goodness but your site is predominantly content-based, then you’re in luck! There is growing interest in the idea of a semantic web, one where pages are easier for computers to read and, just as importantly, to understand. Microformats are blazing a trail here, and it’s easy to see how the likes of hCard (for marking up your contact details in a standard manner) allow your site to expose data to applications using Microformats as a type of API.

Microformats are a simple way of adding meaning to existing HTML by applying standardized semantic class names and other attributes. In addition to hCard, another example of this is the hCalendar format, which allows for marking up event related information such as dates and locations. By pointing a Microformats parser at a site that uses hCalendar, we can extract the event information in a very similar way to using a dedicated API. There are some limitations compared to using a large and complex API, but using Microformats—as well as providing RSS or ATOM feeds of content—is a very simple way of dipping your toe in the water. If you have a more traditional content-based site, this might be all you need to allow people to build interesting additions to it.

Cork’d is a great example of a site making extensive use of Microformats instead of a dedicated API and reaping the benefits. You can find out more about this, and other Microformats examples, in our previous article: The Big Picture on Microformats.

Parsing microformatted data from web pages can be tricky, but there are several tools available to make life easier. Have a look at Drew McLellan’s PHP5 Microformats parser, hKit, and the Ruby equivalent, Mofo, for instance. XSLT can also be used in clever ways to extract Microformats—most languages feature XSLT processing. See some of Brian Suda’s projects, such as X2V for parsing hCard and hCalendar or the XOXO transforms project, for further details.

If you have very specific requirements for exposing or extracting structured data from your site, you might want to take a look at some of the activities of the Semantic Web Working Group at the W3C, or get involved in the Microformats community itself.

Not The End

In short, an API lets other programs or sites access your content more easily. What happens after that is often in the hands of the developers of both the API and the programs talking to it.

In the next part of this series we’ll be looking at developing some code that makes use of a public API. We’ll introduce the main technologies and acronyms that you’ll need to be familiar with, and then work through a couple of simple examples to get you started on the road to API nirvana.

Books

Related Topics: Scripting, Programming, RSS, XML

Gareth Rushgrove is a web designer and developer living in Newcastle, UK.