Postman is an API development platform that is used to design, build, and test REST APIs. For more information about Postman, refer to the Postman Learning Center.

This section walks you through the steps on how to set up your Postman environment and send requests to the Clumio REST API. Optionally import the Clumio REST API collection into Postman so the endpoints are at your fingertips!

For more information about the Clumio REST API, including a list of endpoints and a link to the Postman collection for your version of the REST API, refer to the Clumio REST API Reference by logging in to the Clumio UI and selecting Help > REST API Reference.

Before You Begin

Define Your Postman Environment Variables

Send a Request to the Clumio REST API

Import the REST API Collection into Postman

Before You Begin

Before you can start working in Postman, perform the following tasks:

• Download and launch the Postman API client.
• Ensure you have a valid Clumio API token. If you don’t have an API token, follow the steps in the Clumio User Guide to generate a new one or refresh an existing one.

Define Your Postman Environment Variables

Variables store values that are used over and over again. By defining variables in your Postman environment, you eliminate the need to manually input the same values for each and every request. All Clumio REST API requests require the following two values:

• Base URL - The domain name (a.k.a., API server URL or URL value) used for your REST requests.
• Token - The API bearer token used to authenticate into the Clumio REST API.

Multiple environments can be created with their own unique set of variables.

The steps in this section show you how to create a Postman environment and set the base URL and token variables. In the following steps, we will be creating a test environment with two environment variables - one named baseUrl representing the base URL variable and another named token representing the token variable.

Perform the following steps to create an environment and set up your Postman environment variables:

1. Log in to Postman.
2. Select File > New Environment. The Management Environments  dialog box appears.
3. Click Add.
4. In the Add Environment field, give your environment a name. For example, Clumio - Testing
5. Configure the environment variable for the base URL with the following values:
   • Variable: Type baseUrl 
   • Initial Value: Leave this field empty.
   • Current Value: Type the domain name that will be used for your REST requests. For example, https://us-west-2.api.clumio.com.
6.  Configure the environment variable for the API bearer token with the following values: 
   • Variable: Type token
   • Initial Value: Leave this field empty.
   • Current Value: Paste the Clumio API token that was generated through the Clumio UI. 

Your Postman environment settings should look similar to the following:

If more than one variable with the same name is available to a request, Postman will use the variable that is narrower in scope. For example, environment variables are narrower in scope than collection variables, so if both an environment variable and a collection variable with the same name are available to a request, Postman will use the environment variable over the collection variable.

Now that your environment is set up, you are now ready to send requests to the Clumio REST API!

Send a Request to the Clumio REST API

To send a request to the Clumio REST API server through Postman:

1. If you have an environment created, select the environment to run your requests within by clicking the drop-down at the top right corner of the Postman app and selecting the environment. For example, select Clumio - Testing.
2. Click the Authorization tab and set the following authorization details:
   • Type: Select Bearer Token
   • Token: Paste the Clumio API token into this field. If the token is set as an environment variable, replace the token with the variable name. For example,  {{token}}. 

3. Click the Headers tab and set the following HTTP request header to specify the REST API version you want to use: 
   • Key: Type Accept
   • Value: Type application/api.clumio.*=v<version>+json, where <version> represents the Clumio REST API version to be used. For example, type application/api.clumio.*=v1+json to use REST API version 1. For more information about REST API versioning, including ways to customize the string, refer to the Clumio REST API Reference.

 For example, 

4. In the request drop-down (to the left of the URL input field), select the request method. New requests default to the GET method.
5. In the URL input field (to the right of the request drop-down), type the base URL, endpoint path, and any path and query parameters. For example, https://us-west-2.api.clumio.com/users.

If the base URL Is set as an environment variable, replace the endpoint path with the variable name. For example, {{baseUrl}}/users.

Here is an example of a GET request (within the Postman environment set to Clumio – Testing) that lists all users in the Clumio system: 

6. If a request includes body parameters, click the Body tab and specify the data you need to send with the request. POST and PATCH requests often require body parameters.

Here is an example of a PATCH request that disables a user from the Clumio system ("is_enabled":false).

Import the REST API Collection into Postman

The Clumio REST API collection for Postman is a set of Clumio REST API requests that are organized into logical groupings. To get up and running quickly with REST, import the collection into Postman. For more information about Postman collections, go to the Postman Learning Center.

Importing the REST API collection into Postman requires downloading the collection from the Clumio REST API Reference, importing the collection into Postman, and defining the collection variables for the collection.

Before you begin:

• Ensure you have a valid Clumio API token. If you don’t have an API token, follow the steps in the Clumio User Guide to generate a new one or refresh an existing one.
• Open the Clumio REST API Reference by logging in to the Clumio UI and selecting Help > REST API Reference.

Perform the following steps to import the Clumio REST API collection into Postman and start sending requests:

1. From the Clumio REST API Reference, click the Download link at the beginning of the document to download the Clumio REST API collection to your local machine. The file is saved with the name clumio_postman_collection.json.
2. From Postman, select Import > Import File > Choose Files, and select the JSON file you just downloaded. Once successfully imported into Postman, the collection named Clumio REST API appears in the Collections tab of the Postman sidebar. Expand the folder in the collection to see the available requests.
3. In the Clumio REST API header, select View more actions (three dots) > Edit. The Edit Collection dialog box appears.
4. In the Variables tab, set the following variables for the Clumio REST API collection:
   • Configure the base URL with the following values...
     • Variable: Type baseUrl
     • Current Value: Type the domain name that will be used for your REST requests. For example, https://us-west-2.api.clumio.com.
   • Configure the version header with the following values...
     • Variable: Type clumioVersionHeader
     • Current Value: This variable represents the Clumio REST API version that you will be sending with each of your requests. Only change this value if you want to specify different versions for different resources. For more information about versioning, refer to the Clumio REST API Reference. 
   • Configure the API bearer token with the following values...
     • Variable: Type clumioBearerToken
     • Current Value: Paste the Clumio API token that was generated through the Clumio UI. 
5. Click Update to save your collection variables. Every request in the collection will use these configured variables.

   Note that if more than one variable with the same name is available to a request, Postman will use the variable that is narrower in scope. For example, environment variables are narrower in scope than collection variables, so if both an environment variable and a collection variable with the same name are available to a request, Postman will use the environment variable over the collection variable.

6. In the sidebar, click a Clumio request to auto-populate the request details in the Postman builder. If the URL includes optional query parameters, set or delete them. If the request includes body parameters, click the Body tab and specify the data you need to send with the request.
7. Click Send.