RAAK

You know what an API is, right? I mean, it’s easy – Twitter has one, Facebook has one, Google+ will soon have one. And you shake it a bit, and data comes pouring out. Right?

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!