Contact Support | System Status
Page Contents

    Use Postman for API Requests

    In this topic, you will learn how to set up the popular Postman HTTP client to make requests to the Brightcove RESTful APIs. Although you can use curl statements on the command line to make requests, there are several apps that provide you UI and features to make this easier. This document will show you how to use one such tool, the Postman app.

    Install Postman

    Get Postman from postman.com. There is an online version you can use, but we recommend installing the desktop app.

    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. In the steps below, we will be making CMS API requests using Postman, so your credentials should have at least the following permissions:

    • Video: 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.

    You can use this online app if you prefer. If you do, you need to specify at least video-cloud/video/all permissions.

    Get the OpenAPI spec

    Although not required, you can greatly simplify the setup of Postman is to import the OpenAPI specification for the API you want to use. You can do this for any of the Brightcove platform APIs, but for this tutorial, we'll use the CMS API.

    To get the OpenAPI spec, just go to the CMS API Reference and click the Download button:

    Download OpenAPI Spec
    Download OpenAPI Spec

    The downloaded file will be called openapi.yaml

    Import the OpenAPI Spec

    The next step is to launch the Postman app, and then import the OpenAPI spec that you downloaded:

    Set Up a Collection

    Now the API spec is imported, we can generate a collection of requests.

    1. Click APIs.
    2. If you have other APIs, select Brightcove CMS API Reference
    3. Click Generate Collection:
      Generate Collection
      Generate Collection
    4. In the dialog that appears enter a name for the collection like "Brightcove CMS API".
    5. Select Test the API under "How do you want to use this API?"
    6. Click Generate Collection:
      Collection Settings
      Collection Settings
    7. Open the Collections and click on your new CMS API collection:
    8. Expand the collection and click on the videos folder and select the Get Videos request.
      CMS API Collection
      CMS API Collection
      Request Details
      Request Details

    Notice that Postman has set up most of the details for you from the API reference, including the request itself and the params that can be added to it. In addition, you can click the Documentation icon on the right to show the documenation for the request from the API reference:

    Show Documentation
    Show Documentation
    Request Documentation
    Request Documentation

    You will still need to supply some information of your own, however, including the account id and authentication information. You can do this on a request by request basis, but the better way is to create an environment for the request, where you can store commonly used information as variables. We will do that in the next section.

    Create an environment

    The steps below will walk you through setting up an environment for the CMS API requests

    1. Click Environments, and then Create Environment:
      Create Environment
      Create Environment
    2. Give the environment a name like "Brightcove APIs" (you will be able to use this environment for other Brightcove APIs as well, adding new variables to it as necessary).
    3. Click the text "Add a new variable", type in account_id, and then click in the INITIAL VALUE field and enter your Video Cloud account id:
      Enter Variable
      Enter Variable
    4. Repeat the previous step to add additional variables:
      Environment Variables
      Variable Initial Value
      client_id (your client id - see Get Client Credentials above)
      client_secret (your client secret - see Get Client Credentials above)
      access_token_url https://oauth.brightcove.com/v4/access_token
    5. Click Save to save the environment:
      Save Environment
      Save Environment
    6. Go back to your Brightcove CMS API collection and select the environment you created from the environment selector:
      Environment Selector
      Environment Selector

    Environment variables can be referenced by enclosing them in double curly braces - example: {{client_id}}. Postman helps you with auto-completion when you type "{{...". You can try this by going back to the Get Videos request and start typing "{{a" in the Value field for the Path Variable account_id:

    Variable Autocompletion
    Variable Autocompletion

    Enable requests

    Now that you have the environment set up, you can use the variables to test requests. We will look at the Get Videos request first.

    1. If you did not already do so, enter {{account_id}} for the value of the account_id Path Variable.
    2. Click the Authorization tab for the request:
      Auth Tab
      Auth Tab
    3. Under Configuration Options, change the Grant Type to Client-Credentials:
      Auth Grant Type
      Auth Grant Type
    4. Enter the following variables from your environment in the appropriate fields:
      • Access Token URL: {{access_token_url}}
      • Client ID: {{client_id}}
      • Client Secret: {{client_secret}}
    5. Click Get New Access Token:
      Authorization Setup
      Authorization Setup
    6. When the authorization is complete, you can click Proceed or wait for the token to appear. Then click Use Token:
      Manage Access Tokens
      Manage Access Tokens

    Note that Brightcove access tokens expire after five minutes. Depending on what you are doing and how quickly, you may be able to use the same access token several times. When it expires, the CMS API will return an unauthorized error:

    [
    	{
    			"error_code": "UNAUTHORIZED",
    			"message": "Permission denied."
    	}
    ]

    (The exact form of the message may vary for other APIs, but it will be similar.)

    When this happens, simply return to the Authorization tab and request a new token. You should also delete any expired tokens to avoid confusion, as they are of no further value.

    Delete Expired Tokens
    Delete Expired Tokens

    Make requests

    You are now ready to make a Get Videos request.

    1. Go back to the Params tab and uncheck all the Query Params (you can use them, of course, and change the values, but we will just use the default values for this first test).
    2. Click Send.
    3. You should see JSON code appear in the response area below (an array of video metadata objects):
      Response Data
      Response Data
    4. Now we will try a write request (Create Video). Select that request in the collection:
      Create Video Request
      Create Video Request
    5. You will again need to enter for the Account ID Path Variable. You will NOT need repeat the steps in the previous section to set up authorization, because Postman transfers these settings to other requests in the collection. However, you will still need to generate a new access token.
    6. Next, go to the Body tab, where you will see a sample request body from the API reference:
      Sample Request Body
      Sample Request Body
    7. This JSON is editable. The only required field for a Create Video request is the name, so change that value to "Test Video" and remove the rest of the JSON so that your request body is:
      {
      	"name": "Test video"
      }
    8. Now click send (getting a new access token if you need one), and you should see the metadata object for the new video appear in the response area.

    Page last updated on 19 Jun 2021