Use Insomnia for API Requests

Role(s)
API Developer
Topic(s)
Developer Concepts/Tools
API(s)
Analytics API
Audience API
CMS API
Delivery System API
Dynamic Ingest API
Ingest Profiles API
Live API
OAuth API
Once Ingest API
Once Media Management API
Once Status API
Playback API
Player Management API
Policy API
Zencoder API
Type
Support Doc

In this topic, you will learn how to set up the popular Insomnia HTTP client to make requests to the Brightcove RESTful APIs.

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.

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

Set Header in Insomnia
Set Header in Insomnia

Here is what that header will look like for requests with different authentication methods:

OAuth API (create credentials request only)
Authorization: BC_TOKEN YOUR_BC_TOKEN

How to get your BC_TOKEN.

Playback API
BCOV-Policy: YOUR_POLICY_KEY
Live API
X-API-KEY: YOUR_API_KEY
Zencoder API
Zencoder-Api-Key: YOUR_API_KEY
Once APIs
X-BC-ONCE-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 Player Management API requests using Insomnia, so your credentials should have at least the following permissions:

  • Players: 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. The steps below walk you through making some Player Management API requests using Insomnia.

Setting up an Insomnia workspace

In case you work with other APIs, you may want to create a workspace just for Brightcove requests.

  1. Launch the Insomnia app.
  2. Click the dropdown beside Insomnia and select New Workspace:
    Create Workspace
    Insomnia Authorization Section
  3. Enter the name Brightcove and click Create:
    Name Workspace
    Authorization Type
  4. Click the plus sign and select New Folder:
    Create New Folder
    Create New Folder
  5. Give your folder the name Player Management API

Send GET request

Now we are ready to make some API requests.

Make a GET request

  1. Click the dropdown menu icon on your new folder, and select New Request:
    New Request
    New Request
  2. Give the request the name Get All Players, leave the HTTP method as GET, and click create.
  3. Replace the generic request URL with:
    https://players.api.brightcove.com/v2/accounts/account_id/players

    Replace account_id with your own account id:

    New request
    New Request
  4. Expand the Auth dropdown menu and select OAuth 2.0:
    Auth Menu
    Auth Menu
  5. For the Grant Type, select Client Credentials:
    Grant Type
    Grant Type
  6. Enter values for the access token URL, client id, and client secret:
    OAuth Entries
    Access Token URL https://oauth.brightcove.com/v4/access_token
    Client ID your client id
    Client Secret your client secret
  7. Click Fetch Tokens to make sure this works. You should see a response like this:
    Access Token
    Access Token
  8. Click Send:
    GET Request
    GET Request
  9. The response should look something like this:
    GET Response
    GET Response

Send POST request

Now, we will send a POST request with some data. In this case, we will create a new video object using the Player Management API.

To do this, we will duplicate the Get All Players request and modify as we need to. Another nice feature of Insomnia is that when you duplicate a request, all the authentication information is duplicated along with it, so you won't have to set up getting access tokens again.

Make a POST request

  1. Click on the Player Management API folder to show the Get All Players request inside it.
  2. Expand the dropdown menu for the Get All Players request and select Duplicate:
    Duplicate Request
    Duplicate Request
  3. Double-click on the name Get All Players (Copy) and change it to Create Player
  4. Use the same URL as you did for the GET request steps above, but now choose POST to be the selected HTTP method.
    Change Methdo
    Change Method
  5. Click the Body to expand the dropdown menu and select JSON:
    Select Body Type
    Select Body Type
  6. For the Body data, enter the following JSON code for the body (the screenshot following the JSON shows how the request should appear):
    {
    "name": "MySamplePlayer",
        "configuration": {
            "media": {
            "sources": [{
                "src":"http://solutions.brightcove.com/bcls/assets/videos/Tiger.mp4",
                "type":"video/mp4"
                }]
            }
        }
    }
    
    
    {
        "name": "MySamplePlayer",
        "configuration": {}
    }
    
    
    Request Body
    Request Body
    Request Body
    Request Body
  7. Click Send.
  8. Your response will look similar to the following (You can click the Pretty button for more nicely formatted JSON):

    POST Response
    POST Response
  9. You can verify that your player was created by checking in the Players module in Studio.

Environment variables

You may find it helpful to use Insomnia's Environments to save OAuth credentials for different APIs, or to save other information such as your account id and video or player ids.

Below are the steps for creating and using environment variables for the client_id , client_secret and account_id.

  1. Click No Environments in the top-left area of Insomnia to expand the dropdown menu and select Manage Environments.
    Environments Menu
    Environments Menu
  2. In the Manage Environments dialog, click the + sign beside Sub Environments to expand the dropdown menu, and select Environment to create a new environment:
    Add Environment
    Add Environment
  3. Double-click on the New Environment name to change it to Player Management API (or whatever you like).
  4. Inside the curly braces for the environment JSON, add these key-value pairs:
    • "account_id": "your account id"
    • "client_id": "your client id"
    • "client_secret": "your client secret"

    When you're finished, the JSON should look like this:

    Add Environment JSON
    Add Environment JSON

    (The client secret here is blurred out for security reasons.)

  5. Click Done to add the environment
  6. Click No Environment again to expand the dropdown, and select Use Player Management Environment (or whatever name you gave the new environment):
    Select Environment
    Select Environment
  7. Now select the Get All Players request again to reopen it.
  8. Click OAuth 2 to reopen the authentication section.
  9. Delete the client id value, and start typing client_id - you will see a dropdown menu appear showing relevant environment variables, where you should select client_id:
    Environment Variables Dropdown
    Environment Variables Dropdown
  10. Now select the account id in the request URL, and replace it with the account_id variable.
  11. Do the same thing to replace the Client Secret value with the client_secret variable.
  12. Now click Send again to insure that the request still works.

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.