Background
The area where non-developers become most confused when I describe our software initiatives is when I explain that we have built some of our software, like our video publishing platform, with an extensive API to allow it to be controlled programmatically.
This generally creates a blank stare in non-programmers.
Wikipedia describes an API as follows:
An application programming interface (API) is a set of functions, procedures, methods, classes or protocols that an operating system, library or service provides to support requests made by computer programs.[1]
which I am not sure does you any good unless you already knew what an API was.
A Simple Example
Today, I wrote this a simple example to explain the API concept to a non-developer and hopefully this might be helpful to others as well. This is obviously a bit simplified, but I think captures the general concept.
1) Assume we build a web based software service called TemperatureConverter.com whose sole purpose in life was to convert Celsius into Fahrenheit and vice-versa.
2) This simple website has one page, where we enter a number, select if it is in Celsius or Fahrenheit and hit the Convert! button. At this stage the software would do some arithmetic and return back in bold letters the converted temperature.
So if we entered 32 Fahrenheit and hit Convert!, a big bold 0 appears on the screen.
This is a "standard" human controlled User Interface. We have to come to the site, press some buttons, use our mouse and we get our answer.
3) If we then build an API for this application, we would create a protocol by which a piece of software or another website could then communicate with our TemperatureConverter.
Essentially the API defines how a software application should communicate with our website if it wanted us to do a temperate conversion for it. It is the User Interface to our application if our user is a piece of software (typically referred to as the "Client" in this context).
For example, the other website or software application might say: 32 Fahrenheit Convert and our server might reply 0 Celsius
4) Why is this important?
Well now our application is not just limited to people that want to come to our site. Any one can take this cool functionality we built relating to temperature conversion and include it in their website, whether it is a cooking site, a weather site or a scientific calculator site. The client site can also customize the look, feel, presentation of the User Interface that the end-user sees or build a whole new application on top of the API.
Overall, APIs are a Very Good Thing.
They allow functionality to be built in one place and be reused in many places and their use for web-based applications is increasing rapidly.
In practice, some APIs are provided for free, whereas others are paid for, usually on a usage basis, by the client.
I hope this is helpful to some of you!
Extra Credit For the More Ambitious:
Let's look at a real-life part of our Video Publishing platform's API. This is the protocol for updating a video's title and description in our video publishing platform.
Casual readers can stop here because we don't explain any new concepts in this area, just show what an actual API might look like.
The API code itself is in regular font and my comments are in italics.
Sample Request:
This is the request the software client makes our server
POST /videos/ 2a6a4c2a8b42062af20ce207293e04be HTTP/1.1 This identifies the video
Host: ec2-75-101-235-2.compute-1.amazonaws.com This identifies our server
Date: Thu, 17 Jul 2008 14:52:54 GMT This is the time
X-VWS-Client: test-account The client's account name
X-VWS-Accept: xml Defines the format used, XML
X-VWS-Auth: 90a6d325e982f764f86a7e248edf6a660d4ee833 The key (password) confirming the client is who it says it is
post content: title=title&description=description The new desired title and description.
Sample Response : This is the response from our server
HTTP/1.1 200 OK all is ok
Date: Thu, 17 Jul 2008 14:52:55 GMT Here is the time
Server: VideoWebService Who we are
Content-Length: 68 Length of the content
Connection: close This connection is done
Content-Type: text/xml The format of our reply
Video updated What happened. In this case, success!