6/3/2012

Beginner’s guide for journalists who want to understand API documentation

 

Originally published by Chrys Wu on poynter.org, 11 July 2011. This excerpt is republished with permission.

 

There are three letters that have been floating around the media world for several years now: API. Short for “application programming interface,” an API enables software programs to communicate with one another, allowing your programs to share data and interact in a variety of ways.

There have been lots of articles about why it’s important for news outlets to have and use APIs.

To get the most out of an API, a conscientious creator will often produce a guide, called documentation or docs. There is no single standard for API documentation. The quality varies widely, from indexish and orderly, from pretty, to plain, to messy, to incomplete and nonexistent.

Screen_shot_2012-03-08_at_11.03.30_AM.png

Screenshot of Google Maps API Web Services

There aren’t many resources that explain API documentation to non-coders. And because the format isn’t standardized, it’s hard to write a one-size-fits-all guide to reading the manual. But assuming you’re dealing with a well-documented API, here’s an overview of how to figure it out.

 

The fundamental question: What can this API do for me?

Look for mentions of the word “requests.” If you don’t see that, look for the words “REST API,” or something that looks like the latter part of a URL. Within those sections, look for the words “get” and “post.” These are called methods, the specific actions the API can do. (Some developers will call them functions.)

If the documentation is written in plain English, it will be easy to understand what the method is doing. If not, you’ll need someone with more coding experience to help interpret what’s going on. But know this:

  • “Get” asks for something from the API server — as in, GET me the number of times an address shows up in the database.
  • “Post” changes the database by creating, adding or removing something from it — as in POST a new address to the database.

 

In what format can I get the data?

An API usually lets you choose how the data will come back to you, also known as the response format. You’ll usually see “json” or “XML.” Sometimes, you’ll see “txt” or other formats. 

To find format options, search for the word “format” or “response.” Sometimes the format is mentioned at the start of documentation; sometimes, you’ll find “format” in the methods.

 

What does the API need in exchange for what I want?

Sometimes you can make a API request or post without identifying yourself. But API creators often want to know how the API is being used and by whom, so many APIs require a key — an ID unique to the person or program making a request.
Getting a key is generally straightforward. Look for the word “authentication,” “API key” or “APIkey” to get the instructions, and to see which methods (which “gets” and “posts”) require authentication.

[...]

Read the full article on Poynter.org.

 

Comments