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.
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!
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.
In this case, there is a summary section on the front page with the high-level characteristics:
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.
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.
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.
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
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.
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.
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.