Whenever I start working with a new API, it makes me think of the periodic table of elements. Most people my age remember being asked to memorize the information contained in the table at some point in their secondary education. In the decade-plus that I spent as a Chemistry teacher, I was glad that my state's modern educational frameworks had eschewed rote memorization in favor of developing the skills needed to locate specific information within the organizational system of the periodic table. Now, as I continue learning front-end web development, I find myself returning to many of the same lessons I taught my students about making use of information-dense resources. In this post, I will show you how I dove into an unfamiliar API and figured out how to access the data I needed.
An API is an online resource that developers can use to connect their apps to authentic, often real-time data. If you know the right URL, along with a few other pieces of info which are usually provided by the creators of the API, you and your programming projects can access the data contained within. For one of my projects, I chose to use the Ergast Developer API, which provides data on Formula 1 races. My goal was to create an app that displayed the race results for these races, including the drivers' names and where they finished. The API website provided clear guidelines for the use of their work (non-commercial or educational use, etc.) as well as directions on how to request the data you need:
From there, I just needed to replace the "..." with ".json" in order to get the results in the JSON, or JavaScript Object Notation format. If you've ever worked with dictionaries in Python or objects in JaveScript, JSON will look pretty familiar to you. Here's an example of what JSON data looks like:
The key:value pairs match up well with the syntax from other languages. JavaScript programmers would see this as no more than an array of objects, which allows for convenient manipulation of the data returned by an API. There are lots of free APIs to toy around with, and Apps such as Postman that allow you to see the results of various queries to an API without needing to code a web application first.
But getting the correct data from an API is just the beginning of the challenge. Much like a chemistry student gazing upon the periodic table for the first time, it can be daunting to see what a new API returns from a simple GET request. Here are the first 40 lines of what the Ergast F1 API gives me for the most recent race:
The full response was 818 lines of code when formatted nicely. My advice when looking at data like this is to not worry too much about the parts that look unfamiliar. Focus on the information that you are looking for. In the visual above, on line 12 there is a key "Races" whose value is an array. The first element of that array is another object with keys like "raceName", "date", and "Results." In fact, the "Results" object contains an array of the drivers in order of where they finished the race. That's just what I needed, so let's look at how to get that data from the API and into our app.
Before we dive into the process I want to stress that Postman and console.log() are your best friends. Postman will let you get a preview of the data so you know what you have to work with. From there, make sure to use console.log() in order to print out what your code is producing to make sure you're passing along the right data.
The first step for working with the API in JavaScript is to make a fetch request using the correct URL. Double-check the instructions provided by the API, or use Postman to run the request if you're unsure. Here's a GET request using fetch() that produces the JSON data we saw above:
And this is what is logged in the console by that function:
See how this is the same data produced by Postman? That's a good thing. It means our fetch was successful. A few things might look different, such as the order of the keys. I notice that the console ordered them so that keys that contain nested objects are listed before keys with values in the form of strings and integers. The keys with objects as values are also Capitalized, which is a nice touch. At its heart, however, it is the same data, which means we are ready to access the parts we need.
This is where comfort navigating nested objects and arrays is helpful, and diligent use of console.log() is a must. We want to get to the "Results" array, which is pretty deep in the JSON structure:
Note what I did with the data parameter in the last line. On its own, it returns the entire GET request's worth of info, but by tracing our way through the structure of the object we can get just what we want. Here's a closer look at how we did that:
console.log(data.MRData.RaceTable.Races[0].Results))
Let's break that down. The main object returned was MRData, which contained an object linked to a key called RaceTable, which itself contained a key called Races. That key's value is an array. We wanted the first (and only) item in that array, so we used index notation ([0]) to access the first element of that array. That first element is another object, and one of its keys, called "Results", has an array containing info on the drivers in that race listed in finishing order.
Errors have a way of sneaking up on you when typing out lines like this one, so logging it in the console is crucial. Here's what you're hoping to see in the console:
This is exactly the type of array I want to pass on to some sort of renderResults() function. I can imagine it taking an array of 20 driver objects and using them to create HTML elements that show their names, position, and other info relevant to the race. Just like that element you spent 5 minutes trying to find on the periodic table when you were in high school, it was there all along. The tricky part is knowing where to look. Tools like Postman and console.log() are invaluable as you get familiar with this process.