Chances are you either don't know what an API is or you have heard of it but don't know how it works. It's a mysterious technical something. In reality, APIs are easy to understand and easy to use. They make a fun project if you have time to play around, and they might even be useful. While APIs can be complicated, like any technology, the internet and web use of APIs is not difficult to understand.

The acronym API stands for Application Programming Interface. That was easy, wasn't it? Actually the "application" and "interface" bits are somewhat self-explanatory. But together the phrase doesn't mean much.

APIs allow one bit of software to talk and exchange information with another bit of software.

The best way to understand APIs? Think of this website: this page you're looking at is an interface and the publishing software that generated the page you're reading is an application. What if there was another way, another interface, to grab the data on this page? An API is another way to ask for and get data more often presented in more familiar ways, for example, as a web page or data displayed in a software application on your computer. Google, Twitter, and countless online applications provide an API as an additional interface to their data.

What makes web or internet APIs important? Most web applications you use today could not function without a standard way to request and exchange information across the internet and stored on computers in data centers. A good API makes it easy for people to use your software and create other applications from your data.

Because the internet is everywhere, URLs are the most common way to interact with an API. If you don't know, here's a URL:

http://www.bloomberg.com/video/at-25-is-this-the-cheapest-smartphone-ever-FZE6v266QseKbOngYaKkNQ.html

A URL is a Uniform Resource Locator, or in plain English, a unique address to content online. To use an API, you create a unique address (URL) to request and retrieve data you want. The API URL is literally built with pre-defined blocks of data that work as keys to identify values.

For example, Google and Twitter use q= to identify what you want to query (q stands for query, get it?). count is another common pre-defined key and sometimes is called limit. So a URL with q=horses&count=10 would tell an API to get you 10 stories (or whatever data they have) about horses. You also might use q=horses&count=10&order=asc to get the 10 most recent stories about horses, defined by sorting all stories about horses in ascending order (order=asc) then sending you the first 10 stories.

If you're wondering, the ampersand (&) character is used to split the key=value pairs. The computer processing the API URL looks first for the ampersand character then breaks the URL into chunks, for example, q=horses is one chunk, count=10 is another. Then the computer splits each chunk into keys and values, for example, q and horses. The letter q tells the computer to run a query and the horse value tells the computer what to query.

Other bits you'll see in API URLs are a question mark (?) used to indicate the start of the query string, the list of key=value pairs to its right, and %20 which is computer speak for a space. Most computer file names and URLs don't use spaces. Only humans do. Computers use instead %20 or a dash (-) or an underline (_) character.

Here's a fake example URL used to request and receive data, specifically, the most recent 10 bits of data about horse barns (the horse%20barns bit):

http://mysite.com?q=horse%20barns&count=10&order=asc

The q=horse%20barns&count=10&order=asc portion of this URL, after the ?, is called a querystring.

Once you become familiar with this idea of keys and values used in URLs, it becomes easy to read API URLs. The big question is what keys the API provides you and any limitations. For example, there often is a limit to how much data you can retrieve with one API call. The order of your key=value pairs should not matter but it also is worth looking up.

Typically, web APIs include detailed documentation about the key=value pairs offered. There also are online services like Yahoo! Pipes which is an utterly brilliant way for non-technical people to collect data easily from many different sources online. And it is fairly easy to create a simple web page with JavaScript to retrieve then display API results.

As you use APIs and read their documentation, be sure to investigate these issues in addition to looking up what data you can retrieve:

• API Keys — some APIs require you to sign up and validate your identity before you can use their API. It also helps sort out your requests from other requests.
• Formats — All APIs output data with some minimal structure, for example, with HTML or XML or JSON. Which to use depends on your needs. JSON is probably the simplest form of output because it returns data in key:value pairs, for example, title:"What is an API?".
• Rate Limits — All APIs have a limit to how often you can query their service, in addition to how much data you cn retrieve. As you build and test the URL to retrieve API results, for example, it's possible you will be shut off for some period of time, usually an hour.

There's a lot more you could learn about APIs, for example, delivery methods like REST and SOAP but you don't need to know them to use URLs to request then pull data with a web API. I plan to write more about other aspects of APIs in future issues of this magazine. So please subscribe already! If you have subscribed, thank you for your support!

Learn More

Using APIs: Not Quite Hard as it Looks

http://gigaom.com/2010/10/29/using-apis-not-quite-as-hard-as-it-looks/

API (Wikipedia)

http://en.wikipedia.org/wiki/API

Yahoo! Pipes

http://pipes.yahoo.com/pipes/

apigee API Building Tool

https://apigee.com/console/nytimes

Programmable Web API Search Engine

http://www.programmableweb.com/

Ted Eytan, MD: The wonderful things that come from a health system API : #activetransportation

Explains the Flickr photo included with this article.
http://www.tedeytan.com/2014/03/17/17355