Maybe you have an idea for your website or mobile application, but you’re not quite sure how you can get the data you need to make it work.  Or maybe you’re planning a redesign of your existing website or application and all the technical people around you keep talking about “APIs” without explaining what they mean.  In either case, this post will give you a bit more context and background so you can move forward and get that data you need.

What Is an API, and Why Would You Use One?

The term “API” refers to “Application Programming Interface,” but that’s not a self-explanatory phrase for most people.  At its most generic, an API is a way to exchange information or data between systems.  That might sound really simple, but a good API will help solve otherwise very difficult problems.

 

Here’s a specific example of how an API solves problems: during the summer, the Chicago Park District posts daily (and sometimes hourly) updates regarding the condition of its beaches.  At each individual beach, people can see information about possible swimming hazards, including current water quality data.  That water quality data isn’t being tested and posted by each individual lifeguard at each beach; it’s getting pulled into the website via an API that the city of Chicago provides: https://data.cityofchicago.org/Parks-Recreation/Beach-Water-Quality-Automated-Sensors/qmqz-2xku.

From a business process perspective, here’s what’s happening:

  1. Someone collects a water sample and records that in the City of Chicago system;
  2. The City of Chicago system has that data publicly available via an API;
  3. The Chicago Park District website uses the API to automatically pull in and display that water quality data as soon as it’s available.

At no point in this process does anyone have to manually coordinate a way to get this data into the website.  In fact, no one in any of the three steps above even needs to know who’s responsible for the other steps.  Nor do these systems have to be like each other in any way — they could be written in entirely different languages using completely different technical platforms.  The API makes it possible to seamlessly exchange data without having to worry about any of the messy collateral details.

So How Does the Magic of an API Work?

There are are a few key ingredients to a good API that other people can use:

  • Clear instructions
  • Good documentation
  • Examples of code usage
  • Regular updates to all of the above

In the Chicago Park District beaches example, for instance, we’re using the documentation provided here.  This has all the elements we need.

APIs and Your Project

All well and good, but what does this mean for your specific project?  First and foremost, now you know what you need to ask for: if you’re looking to bring in some external data, you need to find out if there’s an API that could give you access to that data.  The existence of an API is just the first step, however:

  • Is it documented, including clear examples?
  • Has it been thoroughly tested?
  • Is it currently supported?

If the answer is “no” to any of the questions above, then you can still use whatever API is on offer, but your project risk is significantly increased.  If there’s no documentation, you and your team will need to guess at how to use it — are some fields required?  Are some fields expecting only certain kinds of data (like numbers) and just stuck on others (like a piece of text)?  Has it been used in a similar scenario to the way you’re trying to use it?  How will you know if something changes?  Figuring this out on your own will mean more time and more money.

If, on the other hand, you’re working with a well-documented and supported API, pulling that external data into your own site will likely be quite easy and inexpensive.

It’s also worth noting that API usage can go both ways — you can use your website to send information elsewhere, too.

Examples of API Use in the Wild

We’ve already provided one example of API usage above, but there are very few website or custom application development projects that Clarity executes without leveraging APIs of some sort. 

Here are a just a few examples:

Civilian Office of Police Accountability (COPA): Citizen complaints are sent to an external case management system as soon as the complaints are submitted.

City Tech Health Atlas: Chicago health data are made publicly available to anyone who wishes to use it.

Cook County: The website uses the Google Maps API to allow residents to locate offices and county-sponsored events.

Metra: The website uses external transit data to display accurate, real-time schedules and alerts.

A more in-depth case study can also be found here, based on a discussion of Utilizing APIs with ActiveNet.

The examples above encompass both types of usage — pulling data into a website as well as sharing it externally.  The user experience is seamless and in-context, because all the hard work of pulling the data together is done behind the scenes using robust APIs.

Kelly Tetterton is a Partner at Clarity, where she oversees the entire web experience practice.  Here, she discusses what an API is and when and where it makes sense to use one.