In essence, an API or Application Programming Interface is a set of rules, set out in a program that allows other entities to talk to it. ‘Talking’ might involve requesting data or sending information upstream to be recorded, or invoking a function of a program from outside the program. The ‘conversation’ is very short, involving just a request and a response. The entity which ‘talks’ to the program is not usually a human, but another program.

To say that APIs are useful would be a colossal understatement. APIs are ubiquitous in the I.T. world but here at Phoenix Web we mostly deal with web APIs as these tend to be the most relevant to website functionality. These web APIs are involved in almost every aspect of the functionality of the internet.

API Examples

Here are a few typical real-life scenarios where your website communicates with an API:

• You run an eCommerce store and ship products via a third-party courier, say Fastway for example. When a customer puts items in their cart you need the courier to calculate the shipping cost. Your website sends the customer’s address and the item’s quantity, weight and dimensions in a HTTP request to the courier’s API, which will return a calculated price to display on your website.
• You want to display a map of your business location in your website contact page. Your website sends an address to the Google Maps API. The API will then return a rendered map for your website.
• You have a website and a Twitter account. You want to show a feed of your tweets on your website. Your website sends a request to the Twitter API asking for the last 5 tweets. The Twitter API sends back the tweets in a package of data. Your website then takes the data and displays the tweets as HTML on the screen.

REST APIs

When interacting with a web API, the ‘conversation’ usually takes place in the form of HTTP requests. The conversation starts when your web application makes a HTTP request. The API of the other web application fulfills that request and sends a response back. The ‘conversation’ lasts mere milliseconds.

This type of interaction is based on an architectural style for building APIs called REST or REpresentational State Transfer. REST replaced older more complex mechanisms like SOAP and RPC. With these older mechanisms, the requesting computer had to send a heavy package of data to the API. REST allows us to use the same mechanism used when you visit a website in your browser. In fact, with many APIs you can see responses on your screen in your web browser by visiting a RESTful API with the correct URL.

Here’s an example of the advantage of REST taken straight from the blog of Dr Elkstein. Let’s say for example you needed to query a phonebook application for details of a particular user. The phonebook application is at http://www.acme.com. Using SOAP the request might look something like

<?xml version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:body pb="http://www.acme.com/phonebook">

<pb:GetUserDetails>

<pb:UserID>12345</pb:UserID>

</pb:GetUserDetails>

</soap:Body>

</soap:Envelope>

If the API is built in the REST style, the request would look like this:

http://www.acme.com/phonebook/UserDetails/12345

Further Reading

If you want to learn more about REST, you can find out at this StackOverflow question and the Wikipedia REST article.

Read more about APIs at Programmable Web where APIs are explained using a handy wall socket metaphor and API Evangelist which describes some history of APIs.