Everyone who thinks they know what an API is, normally thinks of a very specific type of API, namely a RESTful web API.

This usage of the word API has become mainstream with the rise of web mashup culture. In the software development industry, however, the term has existed for about as long as programming languages, with a much wider definition.

If you understand what the real meaning of the word API is, it becomes much easier to understand the underlying details of web API’s.

Application Programming Interface

API, as you may have guessed from the subtitle above, is short for Application Programming Interface.

In software development, the term Interface refers to a set of rules and conventions that has to be followed by two pieces of software that wants to communicate with each other. In other words, any piece of utility software that is meant to be incorporated in other pieces of software, implements an interface. This interface is then documented in (almost) human language, to tell software developers how to write software that can communicate with it.

And this is literally what software development is all about.

Every piece of software can be broken down a huge number times into smaller pieces of software, which can each be broken down into smaller pieces of software, etc. All these pieces communicate with each other and access each other’s hidden functionality by asking the right questions in exactly the right format – ie through Interfaces.

Web API

Mostly, software speaking to each other reside on the same computer. Often they are even packaged into the same piece of software.

At some point, though, someone realised that computers should be able to phone each other, like humans do, and networking was born.

And, of course, the need for Interfaces to be usable across networks, and the Internet, making it possible for pieces of software residing on different computers to speak to each other. Nice, eh?

REST API

Now, at first, these web API’s utilised various data protocols to speak to each other, of which XML-RPC and SOAP were probably the most widely used. These protocols always depended on quite a few suites of utility software to be installed on each side of the network connection, to facilitate the communication.

However, at some point some genius came up with the following idea: Why don’t pieces of software just publish their output as web pages, accessible by URL, like normal web pages? Bloody Brilliant!

And this, in simple terms, is what we call a RESTful API. An API that is accessed in exactly the same way web pages are.

Not all API’s can be RESTful

RESTful data representation is static. In other words, you ask for a piece of data, and you get sent a page with the data on it. The data will not change on the page while you’re looking at it. This means the data you can get through REST API’s always dates from before the API call was made.

This is perfectly fine for most API needs.

However, Twitter has an entire class of API’s which do not lend themselves to this kind of representation. They are the Streaming API’s.

The streaming API’s are future directed.

It is like opening a pipe to Twitter, through which, from now onwards, you will receive every Tweet you are supposed to receive as they arrive at Twitter, in real time. The data you get through these API’s always dates after you have made the API call.

Ok – that’s enough. That’s more than enough to keep you thinking for one week, and covers all of the social network API’s out there anyway.

Next week, we’ll have a look at OAuth. Or, if you really feel strong, go read the OAuth RFC!

This is what happened in their shop window. As it turns out, a lot more was happening in the engine room.

Foursquare BC

Before launching their new venues API (beta), finding something useful to do with Foursquare’s data was notoriously difficult.

Let’s take, for example, the problem of finding only venues with lots of checkins, in real time. This proved to be a major problem for us while building WOOS.at (mobile only)

These are the limitations:

• Foursquare’s normal API calls are rate limited to 500 calls an hour.
• Because of the low barrier to creating venues, the checkin-to-venue ratio is ridiculously low.
• A maximum of 50 venues can be queried from Foursquare per venue search on the API.
• There is no control over which venues are returned. If a venue is not in the 50 returned by a venue search, there’s no definite way of getting it.
• The search radius for venue searches on the API is 40km.

Given these limitations, it is possible to process 50 venues, 500 times an hour. This sounds like a lot, but 25000 venues an hour is not that much when you’re trying to discover trending venues in real time. Especially if you’re firing shots in the dark, and hoping for the best (hitting the same empty venues over and over).

In steps the new venues API.

Foursquare AD

At face level, it doesn’t look like much, until you give it a second look, and read the fine print:

• The new API is meant for userless access. This means it is built for bot usage, as opposed to front end usage. Ideal for determining venue trends in real time.
• The new API is rate limited at … 5000 calls an hour!
• There is a new API call, venues/trending, which automatically returns only the trending venues within a configurable radius (up to 2km)

Suddenly, even 500 calls an hour would’ve been enough.

Foursquare Beyond

Foursquare has a very vast location database. They have achieved this by making it extremely easy to create venues, and by being the first to do so. That is a very valuable resource, if dealt with correctly.

Up to now, Foursquare’s venues database was kind of proprietary, in the sense that its usability did not allow it to easily get a life of its own outside of Foursquare itself. It was mainly used for checkins.

By making their venue database accessible and usable, Foursquare have increased the value of the database by an immense amount. Add to this their actual reason for launching the new venues API: Mapping Foursquares venue data to other venue databases, like Facebook, Twitter and Google places.

Suddenly the future looks a lot brighter for Foursquare (and its API consumers)!