Talking Tech: Navigating the CFBD API with Insomnia

There are a lot of good tools for working with APIs. Historically, Postman has been ubiquitous in this area. While Postman is still a great tool, I ditched it a few years back for a competing tool called Insomnia. If you've never used either of these tools, you may be wondering what they do. Mainly, they provide a convenient user interface for interacting with API endpoints. You can add an endpoint, and configure its URL, query parameters, request body, and request headers. Then you can call that endpoint and explore its output. You can do all of this in the UI without having a write a line of code. The benefit is you can quickly get to experimenting and testing out APIs right out of the box.

Here is an example of what this looks like querying the /games endpoint of the CFBD API:

You can see all of the configuration needed to call the endpoint laid out in the middle panel, including the URL, setting query parameters, and any other additional properties. Here we configured the request to query all 2022 games. After sending the request, the formatted payload appears in the right panel.

If you look at the left panel, you can see that I have all endpoints in the CFBD API available to me and searchable.

Looking at the middle panel more closely, I already have all available query parameters prepopulated for each endpoint. I can fill these in and enable/disable them at my leisure. Normally, you would have to manually add each endpoint and its available query parameters. Luckily, Insomnia has a very nice feature where you can auto-import an API collection from a Swagger or OpenAPI specification. We'll detail some steps for doing this further down.

For now, lets check out some more features of Insomnia that are worth noting. One of my favorite features is the ability to autogenerate code from any API call. All you need to do is to click on the little arrow to the right of a given endpoint and select 'Generate Code':

From there, you can select from one of many popular programming languages:

And the code will auto-generate:

Another great feature is JSONPath response filtering. Oftentimes, the response payload will be quite large and perhaps you'd like to filter it down because you're looking for a specific item. This is where JSONPath comes in. Using the /games response above, let's say I wanted to see ids for all games in the response body with an excitement index greater than 15. The JSONPath value would be $[?(@.excitement_index > 15)].id and filters and transforms the output as seen here:

If you're interested in using Insomnia to work with the CFBD API, then read on. We'll walk through some steps to get things configured.

Configuring Insomnia for the CFBD API

Here are some simple steps for getting Insomnia up and running with the CFBD API. First off, we presume you already have Insomnia downloaded and installed. If not, then please do that before proceeding.

Now, let's go ahead and visit CollegeFootballData.com. On the right sidebar, you should see a convenient "Run in Insomnia!" button. Click it.

A new browser tab will open. Click on the "RUN CFBD" button.

If an alert box pops up, click on the "Open Insomnia" button.

Insomnia will open and present you with an import dialog. Click on "Scan".

And then "Import".

This will create a new Document. Go ahead and click to open the Document.

Click on "SPEC" and the top of the window. This will show the Swagger documentation. Then, click on "Generate Request Collection".

You will now see all of the CFBD API endpoints available to you and ready to call. However, there are a few more small steps needed before we can do that.

We need to configure our Insomnia environment. Select "Swagger env" from the environment icon at the top left. Once selected, click on the gear icon just to the right.

In the dialog that opens, add a key called base_url and give it a value of https://api.collegefootballdata.com. Afterwards, your environment config should look like this:

And with that, you are largely all set! You should now be able to configure and call any of the endpoints. Although, there is one pesky little detail we haven't looked at: authentication. Select any of the endpoints and click on the Auth tab. Click on the arrow to the left of the "Auth" text and select "Bearer Token".

Paste your API key into the "TOKEN" field. Note: you do NOT need to prefix your key with "Bearer". You don't need to add "Bearer" anywhere. You can leave the "PREFIX" field blank.

And that is about it. One minor annoyance, you will need to configure auth for each and every endpoint. If you want an easier way, there is a plugin you can install that will automatically configure auth for you. I highly recommend doing this. This is the Global Headers plugin. Click here to go to the plugin page and click "Install Plugin" to install it into Insomnia.

Assuming you now have the plugin installed, you can now set the Authorization header as a global environment variable. Go ahead and click again on the gear to the right of "Swagger env" at the top left.

Modify the environment configuration to look like below, replacing <token> with your API key. Note that the value IS prefixed with "Bearer" here. Be sure to keep that part in.

Or you can just copy the below content, paste, and modify it in your instance.

{
	"base_path": "/",
	"scheme": "https",
	"host": "api.collegefootballdata.com",
	"base_url": "https://api.collegefootballdata.com",
	"GLOBAL_HEADERS": {
        "Authorization": "Bearer "
    }
}

You should now be able to call any of the endpoints without needing to add auth details.

Okay. Now we are really done. There are a few caveats to be aware of. First off, this will import Patreon-exclusive endpoints. You will get an HTTP error if you try to call any of these without the appropriate Patreon subscription level. Secondly, this will not automatically update when the API updates. For example, when new endpoints are added or modifications are made to the query parameters in existing endpoints. In this scenario, you will need to redo all of these steps. You'll notice that Insomnia imported the Document with the CFBD API version number. CFBD API versions follow standard versioning in the format of <major>.<minor>.<patch>. You will typically only need to reimport the configuration when a major or minor version changes. And even then you may not necessarily need to based on whatever has changed.

I hope you found these steps helpful. More importantly, I hope you find Insomnia to be a useful tool. As I said, it is my goto for quickly testing any API, including the CFBD API. If I want to debug something, it's the first program I open. And we've really only touched the surface of its functionality.

Cheers!