What is an API?

A game designer asked me the other day to explain the meaning of "API" - and I thought, wow, that is a good question, considering our massive (over?)use of the term on the web. Of course, the obvious meaning is "Application Programming Interface", but that's pretty damn non-helpful, particularly for a non-programmer. So here's what I told him:

There's the traditional meaning of "API" -

Some programmer writes a library with lots of functionality in it, and exposes the functionality as different functions, so that other programmers can just call the functions.

For instance, I could write a function that goes through all the complex steps of making out:

function makeOut(passionLevel, partsOfBody) {
 for (each partOfBody in partsOfBody) {
   partOfBody.kiss(passionLevel);
   lookIntoEyes();
   sighDeeply();
 }
 moanDaintily();
 complainAboutPeopleWatching();
}

So if you want to have your code make out, then you could just call:

makeOut(10, ["neck", "ear", "mouth"]);

You don't have to worry about the "implementation details" - all that code I wrote - you just know that it works.

The "library" is the actual code, the "API" is what programmers need to know in order to use it.

So my API documentation would provide the minimal info needed to use the library, and it could look like this:

makeOut(passionLevel: Number, partsOfBody:Array)

For an example of actual API docs, Java has the online documentation for all of its common libraries here: http://java.sun.com/j2se/1.5.0/docs/api/.

And then there are "Web APIs" -

A Web API hosts all of its code on one server, and documents how other servers can call that code.

There are JavaScript Web APIs, like the Google Maps API, where the Javascript is publicly viewable but quite "obfuscated" (compressed, hard to read).

This is our actual code: http://maps.google.com/intl/en_us/mapfiles/148e/maps2.api/main.js

This is our API documentation: http://code.google.com/apis/maps/documentation/reference.html

Developers only need to know what the API looks like, they don't have to figure out what all that crazy code means.

Then there are HTTP APIs, which means that all of the code is hidden on the server, and the code is executed when a programmer hits a particular URL. Often times, these APIs will create new information on the server for a user. All of our consumer products with user data have HTTP APIs - like Google Spreadsheets, Google Calendar, Blogger, etc. A programmer can hit a particular URL with an authentication header, and either get or create more user data.

One of the most popular HTTP APIs is the Flickr API, which can be used to retrieve information, upload photos, create albums, etc. Their API is documented here: http://www.flickr.com/services/api/

You can use the API without authenticating if you just want to do a simple search:

http://api.flickr.com/services/rest/?method=flickr.photos.search&api_key=4d12a2ccfa7400584c162bfc104bf682&tags=fox

Notice the query parameters after the "?" like method, api_key, and tags. These are like the parameters to a function (like passionLevel and partsOfBody from above). You could imagine that flickr has code on their server that looks like:

function searchPhotos(api_key, tags) {
 ....
}

But once again, a developer never has to see the Flickr server code, they can just use the API and get the results they want.

Above all, an API is a promise.

It's a promise that no matter how the author changes the code (the implementation), the interface will remain the same. You can always call that makeOut function, and expect it to make out, even if it stops complaining about people watching.