Use Postman for HTTP Requests

In this topic, you will learn how to set up the popular Postman HTTP client to make requests to the Brightcove RESTful APIs. Some find curl statements and the command line, used for most of the examples in this section of the 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 such tool, the Postman app.

Install Postman

Get Postman from www.getpostman.com. Postman can be installed as a Chrome or Mac app. We recommend getting the desktop client, but the Chrome version will run on any platform and is identical in functionality and appearance.

Get client credentials

To work with the Brightcove APIs, you will need client credentials for the account and API(s) you wish to use. Get you client credentials in Studio by following the directions in Managing API Authentication Credentials Managing API Authentication Credentials. In the steps below, we will be making Player Management API requests using Postman, 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 get credentials that will work for multiple accounts if you like.

Using Postman

Once you have your client credentials, you are ready to start using Postman. The steps below will walk you through making some Player Management API requests using Postman.

Setting up Postman to get access tokens

  1. Launch the Postman app.
  2. Go to the Authorization section:
    Postman Authorization Section
    Postman Authorization Section
  3. For the Type, select OAuth 2.0:
    Authorization Type
    Authorization Type
  4. Click Get New Access Token
  5. In the dialog, enter the following information:
    • Token name: (enter some name)
    • Auth URL: (leave blank)
    • Access Token URL: https://oauth.brightcove.com/v3/access_token
    • Client ID: (enter your client id)
    • Client Secret: (enter your client secret)
    • Scope: (leave blank)
    • Grant Type: Client Credentials
    • Check Request Access Token Locally
    Grant Access Token Dialog
    Grant Access Token Dialog
  6. Click Request Token
  7. Click on the name of the token to see you now have access to the new token:
    Access Token
    Access Token
  8. To use this token, select it, make sure Add token to selector is set to Header, and click Use Token
    Set Access Token
    Set Access Token

Send GET request

Now we are ready to make API requests.

Make a GET request

  1. Now enter the following URL into the Enter request URL field, substituting your account id for {account_id}:
    https://players.api.brightcove.com/v1/accounts/{account_id}/players
  2. Leave the method as GET, and click Send:
    GET Request
    GET Request
  3. 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.

Make a POST request

  1. Use the same URL as you did for the GET request steps above, but now choose POST to be the selected HTTP method.
    POST Request
    POST Request
  2. Click the Headers button:
    Headers Section
    Headers Section
  3. Click on "key" to enter a new key - value pair Content-Type - application/json. Simply begin typing in the input areas and you will be supplied with options from which you can choose the indicated values.
    Add Header
    Add Header
  4. Click the Body section just under the URL, then the raw radio button:
    Request Body
    Request Body
  5. For the raw 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
  6. Click Send.
  7. Your response will look similar to the the following (You can click the Pretty button for more nicely formatted JSON):

    POST Response
    POST Response
  8. You can verify that your player was created by checking in the Players section of Studio.

Environment variables

Although you can create client credentials for multiple accounts and any combination of API operations, you may wish to maintain greater security by limiting the scope of your credentials to a single account and API (or even specific API operations). If so, you can take advantage of Postman's environment variables to simplify testing requests across multiple accounts and APIs. The key is to set up environments corresponding to each set of client credentials that you use.

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

  1. Click the gear menu in the top-right Postman and select Manage Environments.
    Environments Menu
    Environments Menu
  2. In the Manage Environments dialog, click Add.
    Add Environment
    Add Environment
  3. For the new environment, enter:
    • A name (whatever you like)
    • An environment variable called client_id with a value of your client id
    • An environment variable called client_secret with a value of your client secret
    Add Environment Variables
    Add Environment Variables
  4. Click Add to add the environment
  5. Optionally, if you use Postman on multiple systems, you can share the environment and be able to access it on your other systems if you upgrade to Postman Pro. To do this, click the Share button in the environment listing.
    Share an Environment
    Share an Environment
  6. If you do share, in the Environment Templates dialog, click Share to share the environment.
    Add Environment to Shared Environments
    Add Environment to Shared Environments
  7. Add more environments for additional client credentials
  8. Close the Manage Environments dialog to return to Postman and select one of your environments from the menu.
    Select an Enviroment
    Select an Environment
  9. Now click Get New Access Token again, but change the hard-coded values for Client ID and Client Secret to point to the environment variables {{client_id}} and {{client_secret}}
    Use Environment Variables
    Use Environment Variables
  10. Postman will remember these values, so when you change to a different environment for another API or account, you will be able to get access tokens without changing the client id and client secret values.