Use Postman for API Requests

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:

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:

Open the Collection

As the API is imported, Postman will generate a collection of requests.

1. Click Collections.
2. Select the new CMS API collection:
3. Expand the collection and click on the videos folder and select the Get Videos request.

   

   

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. It also provides the documentation for the parameters, let's you edit values, and uncheck the ones you do not wish to send with the request.

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 the Environment Quick Look icon, and then Add:

   

2. Edit the environment name, changing it to "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 (then do the same for CURRENT VALUE):

   

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:

   

6. Go back to your Brightcove CMS API collection and select the environment you created from the 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:

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:

   

3. Under Configuration Options, change the Grant Type to Client-Credentials:

   

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:

   

6. When the authorization is complete, you can click Proceed or wait for the token to appear. Then click Use Token:

   

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.

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):

   

4. Now we will try a write request (Create Video). Select that request in the collection:

   

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:

   

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.

Related topics

• Testing Tools for Brightcove APIs
• Authentication for API Requests
• Online API Tester
• Use Insomnia for API Requests