beanz Magazine

What is an API?

Ted Eytan, MD on Flickr

APIs can be a fun, easy to use, and easy to learn way to retrieve and mash up data online.

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

Also In The April 2014 Issue

How to Make a Twitter Bot

There are a ton of ways to make a Twitter bot. Here are a number of resources, ideas, and clues to follow up.

What is an Algorithm?

Algorithms control our lives online and offline. Here are some examples to show what is an algorithm and how they work.

How to Build Example Bot

I have updated the installation instructions for this Github project to make it even easier to install and play with.

Bot Makers

A collection of bot makers and professor types attend an online bot convention to talk about Twitter bots and more.

File Extensions

You can tell a bit about the software used to create the web page you're reading by looking at the URL in your web browser.

Traceroute

A computer command used to diagnose network problems also lets you see how data hops across the internet.

How to Build a Slightly Complicated Website

Some tips on how to find online publishing services and use them to create your website.

What is an API?

APIs can be a fun, easy to use, and easy to learn way to retrieve and mash up data online.

April 2014 News Wire

Interesting stories about computer science, software programming, and technology for the month of March 2014.

Objects

Many programming languages organize their code into objects, to model their applications and make their code more reusable.

April 2014 Learn More Links

Links from the bottom of all the April 2014 articles, collected in one place for you to print, share, or bookmark.

At bottom, robotics is about us. It is the discipline of emulating our lives, of wondering how we work.