Information for: DEVELOPERS   PARTNERS

Using Postman with the Cloud Platform API

Postman is a cross-platform application that includes tools you can use to both test API calls and confirm their results, which can save you time and frustration when building custom scripts that need access to Acquia’s APIs.

For a full list of Acquia’s public APIs for its products, see Platform APIs.

Installing and configuring Postman

To install Postman on your local computer, download the application from www.getpostman.com/downloads.

After installing Postman, you must generate an Cloud Platform API access token.

Creating a new Postman request

To create a new Postman request, complete the following steps:

  1. Open Postman, and in the top, left corner, click New.

  2. Scroll to Building Blocks, and then click Request to display the Save Request window.

  3. In Request name, enter a human-readable name for your request.

  4. (Optional) In the Request description field, enter a description that will help you identify the request in the future.

  5. Use one of the following methods to add your request to a collection:

    • To add your new request to a new collection, click Create Collection, enter the name of the new collection, and then click the check mark.
    • To add your new request to an existing collection, provide the name of an existing collection in Search for a collection or folder, and then click the magnifying glass icon.

    For more information about collections, see Creating collections.

  6. Click Save.

    Example of the Save Request modal window

After you create the request, you must authorize it.

Configure authorization in Postman

The Cloud Platform API requires an access token to be sent with every API request.

For help generating an Cloud Platform API access token, see Generating an API token.

To send an access token with your requests, complete the following steps in the Postman user interface:

  1. Open Postman.

  2. In the left column, click Collection, and then click the collection to display the requests it contains.

    Select a collection, and then select a request within it

  3. Click a request to select it. Postman displays information about the request.

  4. In the menu, click Authorization.

    Select the Authorization option from the menu

  5. In the Type list, click OAuth 2.0.

  6. In the Add authorization data to list, click Request Headers.

  7. Click Get New Access Token to display a Get New Access Token window.

    Fields describing your new access token

    • Token Name: The human-readable name of your token.
    • Grant Type list: Click Client Credentials.
    • Access Token URL: Use https://accounts.acquia.com/api/auth/oauth/token.
    • Client ID: Enter your Cloud Platform API key. To create one, see Generating an API token.
    • Client Secret: Enter your Cloud Platform API Secret. To create one, see Generating an API token.
    • Scope: Leave this field blank. For more information about scope, see Understanding scopes for OAuth Apps on GitHub’s Developer website.
    • Client Authentication list: Click Send as Basic Auth header.
  8. Click Request Token to display the Manage Access Tokens window.

  9. In the Token Name field, enter a human-readable name for your token.

  10. Scroll to the bottom of the window, and then click Use Token.

You now have an authorization token you can use when making Cloud Platform API requests. For the process to regenerate the token when it expires, see Regenerating an access token.

Creating a new API request in Postman

After generating an authentication token in Postman, you can use the token to communicate with Cloud Platform API endpoints. To initiate a call to the Cloud Platform API through Postman, complete the following steps:

  1. Open Postman.

  2. In the left column, click Collections, and then click the collection to display the requests it contains.

  3. Click a request to select it. Postman displays information about the request.

  4. In the list of Cloud Platform API endpoints, identify the endpoint you want to access.

  5. In the Method list, click the method of the endpoint (such as GET or POST) you want to access.

  6. In the Enter Request URL field, paste in the full URL of the endpoint. Cloud Platform API endpoints begin with the string https://cloud.acquia.com/api. Most contain placeholders inside curly braces, such as {applicationUuid}, which you must replace with live data from your application.

  7. Click Send to have Postman send your request. In the following example, the endpoint URL contains placeholder data:

    A request with placeholder data, ready to send

  8. In the menu, click Headers, and then in the sub-menu, click Body.

    The body of a response, displayed in JSON format.

Postman displays the body section of your request in JSON format.

Regenerating an access token

Access tokens are temporary and will expire. If, after sending an API request, Postman displays a response message similar to the following in the Headers section, your access token has expired and must be regenerated:

{
    "error": "unauthorized",
    "message": "The access token has expired."
}

To regenerate your access token in Postman, complete the following steps:

  1. Open Postman.
  2. In the left column, click Collection, and then click the collection to display the requests it contains.
  3. Click a request to select it. Postman displays information about the request.
  4. In the menu, click Authorization.
  5. Click Get New Access Token to display the Get New Access Token window with the information you provided when you created the previous token.
  6. Click Request Token.
  7. Scroll to the bottom of the window, and then click Use Token.

Postman generates a new access token for your use.

Troubleshooting issues in Postman

Postman provides the Postman Console to help you with debugging your requests. To display the console, click the console icon at the bottom left of the Postman interface, as shown in this example:

Postman Console icon in the user interface

For more information about the Postman Console, see Debugging and logs at the Postman Learning Center.

More resources