Approaching a New API

Walkthing through how to approach a new API like that of the New York Times.

Scroll down...




To ease into working with APIs, this lesson will explore how to approach a new API. We'll use the New York Times API, specifically the "Most Popular API" because it's RESTful and straightforward. And because we want to see what the week's most popular story has been.

This lesson and the next few will be a sort of combination demo-and-lesson. We'll introduce you to the API here and then how you can make HTTP calls in JavaScript and a custom wrapper for this API in the next lesson.

Getting Started

Step 1 is figuring out where you want to get your data from! The Internet is your oyster. If there is a service that has any sort of interesting data, it's worth Googling for "their_service public API". If it does have a public API, great! If it's free too, then we're really in business!

1. Read the Docs

Google "xyz API docs" and you'll find their documentation. Look through it. Figure out if there is a URL that retrieves the kind of data you’re looking for. Figure out what the usage patterns look like.

In our example, we know that we want the week's most popular story, and the NYT docs show us that this is possible.

API Docs


In this case, there is a summary section on the front page with the high-level characteristics:

API Summary

NYT API Docs Summary

You can see that it's a RESTful API (GET only) that will return JSON, XML, or a PHP-compatible format. If you scroll down, they provide great documentation of the required and available options plus example requests and example responses.

In this case, we can choose between three options to define "most popular" -- most emailed, most shared, and most viewed.

2. Sign Up and Play

Once you've familiarized yourself with what's required, you should sign up for their developer site and get your API key (if it's necessary). That's just going to be one of the parameters you need to make a successful API call.

NYT API Account Signup

Once you've signed up, you can click on "Keys" at the left bar to get an API key:



Once you have your account and API key, you can start making API calls to your heart's content (observe the rate limits though)! Play around a bit. See what data is required and what data is returned. It's 100x easier to do this phase with a simple in-browser HTTP wrapper like the Postman Chrome add-on that lets you specify the headers, authentication, and data that you want.

Even better, sometimes more established APIs will have their own in-browser tools for exploring their APIs. You often don't even need an API key for it since you can use their test key.

API Explorer

New York Times API Explorer

Check out the data that gets returned by your requests and how it's structured. If you're getting back a giant, unformatted, nested JSON object, be sure to copy it somewhere that it can be neatly spaced out and investigated. You'll need to tunnel into these response objects later, so understanding what they look like is important. In our example, they've been kind enough to do the formatting for us so we can see exactly what the returned structure looks like.

API Explorer Results

NYT API Explorer Results

3. Find the Gem or Library

So far, nothing we've done has been particularly focused on the front end or the back end. In fact, because the New York Times is a simple GET-based API, it can be accessed from anywhere -- whether that's a command-line script, an Express server or some browser-based JavaScript. But regardless of how you access it, your next step should be to look for help.

Even if the API seems simple, it's often worth taking a minute to browse the web for gems or libraries which simplify the process of accessing the API. Often the API docs have links to helpful libraries as well. As you'll find out the hard way, there are always quirks with the API process and it's usually best to reap the benefits of someone else working through them.

API "wrapper" libraries are also a good opportunity to read through someone else's code — even if you don't use the library, it can often provide useful patterns for making your own implementation.

In the case of the NYT, there are several gems out there, including their official times_wire gem but it's just a "thin wrapper" around the API (and fairly old) so it's not much more complex than we could have written ourselves.

Additional Reading

Take a look through the NYTimes times_wire gem's lib/times_wire folder and see how it's put together for an example of a reasonable API access pattern. Essentially, they built a Base class to handle the plumbing of the requests and then built Item and Section as thin wrappers over that.

Wrapping Up

This should give you a good sense of how to approach and set up access to a simple third-party API. You got to see how to formulate an API request and how to handle the response.

These simple patterns are all you need to start running amok with most APIs. In the next lesson, we'll demo a more complex API wrapper on the New York Times API you just saw.

Sign up to track your progress for free

There are ( ) additional resources for this lesson. Check them out!

Sorry, comments aren't active just yet!

Next Lesson: Writing the API Wrapper