Use Insomnia for API Requests

Introduction

Some find curl statements and the command line, used for many of the examples in our platform APIs documentation, difficult and intimidating. For those, there are numerous tools to send HTTP requests to REST-based services, which include most of the Brightcove APIs. This document will show you how to use one popular tool, the Insomnia app.

Install Insomnia

Get Insomnia from https://insomnia.rest. Insomnia can be installed on Mac, Linux, or Windows systems.

Authentication

Insomnia can be used to make requests to any of Brightcove's RESTful APIs. Most of the APIs use OAuth2 for authentication, and we will see how to set that up in Insomnia later in this document. However, you can also use it for the APIs that do not use OAuth, by simply setting the appropriate header.

Here is what that header will look like for requests with authentication methods other than Oauth2:

Playback API

  BCOV-Policy: YOUR_POLICY_KEY

Live API

  X-API-KEY: YOUR_API_KEY

Zencoder API

  Zencoder-Api-Key: YOUR_API_KEY

Get client credentials

To work with most of the Brightcove APIs, you will need client credentials for the account and API(s) you wish to use. Get your client credentials in Studio by following the directions in Managing API Authentication Credentials. In the steps below, we will make CMS API requests using Insomnia, so your credentials should have at least the following permissions:

• Videos: Read/Write

You can add as many additional permissions as you like to get credentials that will be usable for a wider range of API requests. Also note that you can get credentials that will work for multiple accounts if you like.

Using Insomnia

Once you have your client credentials, you are ready to start using Insomnia. Insomnia will do a lot of set-up work for you if you import the OpenAPI specification for the CMS API, which we make available to you .The steps below walk you through making some CMS API requests using Insomnia.

Setting up an Insomnia collection for the CMS API

Get the OpenAPI specification for the CMS API

1. Open the CMS API Reference.
2. Click the Download button and save the openapi.yaml file in a place where you can find it again:

   

Import the OpenAPI specification into Insomnia

1. Launch the Insomnia app.
2. Click the dropdown beside Insomnia and select Import/Export:

   

3. In the dialog that opens, click Import Data and select From File:

   

4. Select the openapi.yaml file you downloaded and then choose whether to import the data into the current workspace or create a new one. Either will work, but we recommend creating a new workspace for each API:

   

5. Next you will be asked whether to import the data as a Request Collection or a Design Document. Choose Request Collection:

   

6. You will see a dialog confirming that the data was imported.
7. Click on Dashboard in the upper left corner to see your workspaces. If you created a new workspace, you will see it displayed with the appropriate name:

   

8. Click on the workspace to open it.
9. You will see a list of folders that contain the various groups of requests for the CMS API, and also a new OpenAPI environment:

   

Add variables to the environment

This is an optional step, but it will simplify setting up authentication for requests later.

1. Click on the OpenAPI env dropdown menu and select Manage Environments:

   

2. You will see the environment variables that Insomnia created from the OpenAPI spec in the form of JSON:

   

3. Add these additional variables to the JSON (see Get Client Credentials above on the client_id and client_secret):
   • "account_id": "your_account_id"
   • "client_id": "your_client_id"
   • "client_secret": "your_client_secret"
   • "access_token_url": "https://oauth.brightcove.com/v4/access_token"
4. When you are finished, the environment JSON should look similar to this:

   

5. Click Done in the lower right-hand corner to exit the dialog.

Set up authentication

Now we are ready to set up authentication for API requests.

1. Click the Videos folder, and select the Get Videos:

   

2. Notice that the URL for the request already contains two variables. If you click on these, you can see (and modify) their values. base_url is automatically generated by Insomnia from the OpenAPI spec. If you click on account_id, you should find that the value matches what you entered as an environment variable in the previous section.
3. Click the Auth tab and the Auth dropdown menu, and select OAuth 2.0:

   

4. Click the Grant Type dropdown and select Client Credentials:

   

5. In the Access Token URL field, start typing "access_token_url" - you will see the autocomplete menu, and select your access_token_url environment variable:

   

6. Repeat the previous step to populate the Client ID and Client Secret fields with your client_id and client_secret variables:

   

7. Scroll down to see the Fetch Token button and click it. Make sure you see the Access Token field populated with a token:

   

8. Click Fetch Tokens to make sure this works. You should see a response like this:

   

9. Go to the Header tab and delete the Authorization header (the authentication you just set up will take care of the head - this one will break it):

   

Make a request

Now we are ready to make a Get Videos request.

1. Since this is a GET request, all you have to do is click Send.
2. You should see the JSON response appear in the Response area:

   

3. Note that you can retrieve different sets of videos by using Query params. Click the Query tab for the request, and you will see that Insomnia has populated it based on the OpenAPI spec. Just check the param(s) you want to use and set the values:

   

Send a POST request

Now, we will send a POST request with some data. In this case, we will create a new video object using the CMS API. Start by selecting the Create Video request in the Videos folder.

1. Repeat all the steps in the Set up authentication section above to set up authentication for this new request.
2. This request requires a request body, so click the JSON tab, and enter this JSON code to replace the null:

   {
   	"name": "Insomnia Test"
   }

   

3. Click Send and you should see the new video object returned in the response.

Using the code generators

Another nice feature of Insomnia is that it will generate code for making requests in many different languages.

1. Hover click on the dropdown menu for a request:

   

2. Select Generate Code from the menu:

   

3. In the Generate Client Code dialog that opens, choose the language you want code for:

   

4. For many of the languages, there are also variants you can select that may be a better fit for the kind of app you are creating:

   

5. There is also a handy button for copying the code to your clipboard:

   

Conclusion

You now know the basics of using Insomnia to make requests to the Brightcove APIs. Note that if you choose to upgrade your free Insomnia account to a team account, you can also sync all your requests and environments and share them with other team members.