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.
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 quibble and call them functions. For this tutorial, we’ll stick to methods.)
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. The format is best decided by your developer, but at least you’ll know what’s available.
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. In addition, they want to prevent server overload and head off developer hijinks, 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.
Can I test API requests even if I’m not a developer?
Yes. You can build your own test request by copying the example response found in the method and changing the variables, usually referred to as parameters.
For example, let’s try getting New York Times reviews for the “Harry Potter” movies as an XML-formatted response. Use your favorite search engine to find The New York Times movie reviews API. This API is not perfect (it’s in beta, after all). The steps below can be compressed with shortcuts once you become more experienced, but since we’re assuming this is your first time, we’re going to take the slow road.
Once you’re on the API page:
1) Look for something that allows you to get reviews using keywords. In this case, that’s the “Reviews by Keyword” method. Within the method description is a URI example (the text in the gray box). That’s the template for your request.
Copy it, paste it into a text editor [TextWrangler (Mac), TextMate (Mac) or TextPad (Windows)] and start replacing the parameters, the things in braces and brackets. They’re bolded below for easy reference.
In the Reviews by Keyword method, there are two required parameters: version which is the API version (use v2), and API-key, which you can get right here.
You’d go from this:
http://api.nytimes.com/svc/movies/{version}/reviews/search[.response_format]?[optional-param1=value1]&[...]&api-key={your-API-key}
To this:
http://api.nytimes.com/svc/movies/v2/reviews/search[.response_format]?[optional-param1=value1]&[...]&api-key={paste your API key and here and delete the surrounding braces}
2) Next, set up two additional parameters, which are described a little further down in the same section of the Movie Reviews API documentation:
- The response-format, which will be .xml
- A keyword query — we’ll use query=Potter because searching for ‘Harry+Potter’ doesn’t work. (I know because I tried. Remember, the API is in beta.)
- An opening-date range, from the first film (which came out in November 2001) through the last film (which comes out this week). As the documentation tells you, the format for a range is
YYYY-MM-DD;YYYY-MM-DD, so we’ll useopening-date=2001-11-01;2011-07-31
Your URI example should now look like this (the new parameters are in bold):
http://api.nytimes.com/svc/movies/v2/reviews/search.xml?&query=Potter&opening-date=2001-11-01;2011-07-31&api-key={paste your API key and delete the surrounding French braces}
3) Copy and paste the URI you made into a Web browser address bar. Hit return.
If you made the changes correctly, you’ll get a response similar to what’s on this page. In fact, if you want, you can copy the URI above up to the = before the {, paste it into your browser’s address bar, and add your API key to the end and hit return to see the XML output.
Voilà. You’ve just made your first API call and pulled New York Times “Harry Potter” movie reviews. (Plus a straggler. Again, beta.)
Some API developers are nice enough to include a console, sandbox or fill-in-the-blank form so you can test your requests without hand-building them. Better yet, the tools usually generate both the properly formatted request and the result, which you and your developers can then copy and paste and use as you wish.
You will come across lots of documentation styles as you begin to explore what’s available to you. If you have questions about what you find, feel free to ask them on the Hacks/Hackers help board.
Chrys Wu is a journalist, strategist, coder and cook. When she’s not advising clients on user engagement and community building, she launches and organizes Hacks/Hackers meetups that bring journalists, developers and designers together to reboot news. She’s on Twitter @MacDiva.
Comments