While they can be intimidating at first, APIs are pretty straightforward once you understand their core purpose… and when you do, an entire range of functionality in web development becomes available to you.

An API - standing for Application Program Interface - is a method for getting some result from a request. An old-school calculator might be thought of as a mathematical API: providing the device with some numbers and an operator (divide, multiply, etc) produces a result. At the physical level, a Rock 'Em Sock 'Em Robot set might be considered an API: twiddle with some levers, and watch the robots fight.

APIs were one of the foundational components of modern personal computing. Without them, programmers would have to build every program completely from scratch. Using an API, they can build applications much faster: rather than coding a Close Window button, a programmer can request it from the operating system’s API, importing the functionality into their application, without having to worry about the operation or performance of the UI. APIs also work at the hardware level, allowing different devices and components to communicate with each other.

Web APIs

On the web, APIs take two forms: client-side and server-side.

1. Client-side APIs The HTML5 specification provides a series of APIs to developers for use on web sites, such as the Fullscreen and Dialog APIs. These are accessed via JavaScript, and extend the functionality of the browser to replace native applications. This functionality has caused many in the industry to refer to sites that use these features extensively as “web applications” or “web apps”.

2. Server-side APIs Many companies produce their own APIs: Netflix, for example, has an API that shows the films currently in circulation for subscribers to browse. There are thousands of APIs in existence: some of them for public use, some reserved for use solely inside corporate web sites. These data stores are accessed by making a request from a server.

This article concentrates on the second sense of the term.

Using Web APIs

Google Maps has a fully-fledged API, but we can see a simple variation of it when we bring up a map in a browser. For example, the following URL:

https://www.google.ca/maps/@51.0890235,-114.0293939,12z

…brings up my current approximate location in the city of Calgary. By changing the first two pairs of numbers after the @ (representing latitude and longitude), we change the information requested from the Google Maps API, and gain a different result.

In real-world use, web sites make calls to APIs using JavaScript, PHP, Ruby or another language. Most web APIs return information in JSON, XML or HTML; many have an option for all three. Some APIs require a unique key (allowing the service to track requests and use), others do not. Some APIs have excellent documentation; some do not.

As one example, the OpenWeatherMap API can take a URL that contains a city name and an API key:

http://api.openweathermap.org/data/2.5/weather?q=Calgary
&appid=91f05e4330f6e85cab273b8b1ad8bb71

Used directly in the URL bar of a browser the returns data that looks like the following:

{"coord":{"lon":-114.09,"lat":51.05},"weather":[{"id":
800,"main":"Clear","description":"clear sky","icon":"01n"}],"base":"cmc 
stations","main":{"temp":281.645,"pressure":868.29,"humidity":70,"temp_min":
281.645,"temp_max":281.645,"sea_level":1028.59,"grnd_level":868.29},"wind":{"speed":
1.07,"deg":175.501},"clouds":{"all":0},"dt":1462251211,"sys":{"message":
0.0031,"country":"CA","sunrise":1462277067,"sunset":1462330973},"id":
5913490,"name":"Calgary","cod":200}

As you can see, the data is in JSON format, and contains information about the current weather conditions here in Calgary. Naturally, the typical user would never see the data in this way: I’d make the request via JavaScript or another language, possibly in combination with a wrapper (a helper script to organise and format the returned data) and present the result on the page surrounded by nice semantic HTML. By using appropriate APIs, it's possible to build a far more fully-featured site than one you could reasonably create by yourself.

API calls can be far more specific in the data they return, depending on the query: I could request only the current wind speed for my location, for example, or historical temperature records for today’s date.

I’ll be providing examples of just that and many other uses of APIs in future articles; follow me on Twitter to receive updates the moment they are posted.

Photo by Formerly SS_02_Camaro

Enjoy this piece? I invite you to follow me at twitter.com/dudleystorey to learn more.