Skip to main content

How to Use Postman

You can use Postman to test Server API V3.

Prerequisites:

  • You must have Postman installed. Postman is available at https://www.postman.com/downloads/. Install and create an account. Be sure to use the desktop version of Postman, not a browser version. After confirming your email address, you might end up in the browser version.

    Note

    The web version of Postman can’t access most customers' APIs because their APIs are behind the firewall. Therefore, the web version of Postman can't get there.

  • You must have an API Key and an API Secret in order to test Server API in Postman. Go to the User Roles and Permissions help page for more information.

Add API to Postman

To test Server API, import it to Postman.

Get Your Documentation and Token URLs

  1. To get your Documentation URL, go to the Server UI, select the question mark icon in the upper right corner and then select API Documentation. This will take you to the API V3 Swagger page.

    api_postman_getdetails0.png
  2. Get your Documentation URL. Note the double backslash after "webapi".

    Note

    Localhost will only work if Server is running on the same host as Postman. Otherwise (if it is a remote workstation), you must use the hostname or IP address instead.

    api_address_docu.png

    Example: http://localhost/webapi//swagger/docs/3.

  3. View any API endpoint.

  4. Select the red exclamation point to the right to start the authentication process.

  5. Copy the Token URL. Example: http://localhost/webapi/oauth2/token.

    api_copy_tokenURL.png

Load the Swagger Documentation in Postman

  1. In Postman go to Collections tab.

  2. Select Import.

  3. Enter the Documentation URL found as described in Get Your Documentation and Token URLs.

  4. Select Import.

    api_swagger_load_01.png
    api_swagger_load_02.png

    This adds the Alteryx Server API V3 under the Collections tab at the left.

Create OAuth2 Access Token To Use in API Calls

To be able to send your requests, you must set up your authorization and create an OAuth2 access token in Postman.

  1. Go to Collections and select Alteryx Server API V3.

  2. Select the Authorization tab.

  3. Select OAuth 2.0 as Type.

    api_postman_auth.png
  4. Scroll down the Authorization page to the Configure New Token section.

  5. Set Token Name to YOUR_TOKEN_NAME.

    Note

    We are not providing an input for YOUR_TOKEN_NAME. You can enter any Token Name you want.

  6. Select Grant Type to Client Credentials.

  7. Set Access Token URL to TOKEN_URL_FOUND_ABOVE.

  8. Set Client ID to YOUR_API_ACCESS_KEY.

  9. Set Client Secret to YOUR_API_ACCESS_SECRET.

  10. Set Client Authentication to Send as Basic Auth header.

  11. Select the Get New Access Token button.

  12. Select Proceed.

  13. Select the Use Token button.

    api_postman_auth2.png

Recreate Your Access Token if It Expires

After some time your original token expires and you get a 401-Failure to Authenticate error when accessing the API. To recreate the token:

  1. Select Alteryx Server API V3 on the Collections tab.

  2. Select Manage Tokens from the Available Tokens dropdown menu.

  3. Select the expired token (there will be a line through it).

  4. Delete the expired token.

  5. Create a new token as described in Create OAuth2 Access Token To Use in API Calls.

Use API in Postman

The example below demonstrates a common API pattern to

In the following example, we’ll use the API to retrieve the User ID from the list of users in Server. Then, we'll use that User ID to get the user's detailed information. In the last step, we’ll update the user record using the user's data.

For simplicity, we will change the first name of the user in this example. In practice, it would be best to do this using the Server UI.

api_postman_search1.png
api_postman_search2.png
api_postman_search3.png
  1. Navigate to GET v3/users.

  2. Deselect all eight Query Params (to search the Users collection, select one or more params and enter search values).

  3. Select the Auth tab.

  4. Set the Type to OAuth 2.0.

  5. Select the token you created above.

  6. Select Send.

  7. View the results at the bottom of the screen.

  8. Copy a UserID to use in the next step.

Get a UserID from the example above or directly in the Server UI (by copying it from the URL when you are viewing the User).

api_postman_getdetails1.png
api_postman_getdetails2.png
api_postman_getdetails3.png
  1. Navigate to the GET v3/users/{id} endpoint.

  2. Enter the UserID as the value of the id param.

  3. Select your token on the Authorization tab as in the previous step.

  4. Select Send.

  5. Copy the entire JSON object from the Body section at the bottom of the screen (including the leading and trailing curly braces) to use in the next step.

Get a user's detailed information (the JSON object) in the previous step to use in this step.

api_postman_updatedetails1.png
api_postman_updatedetails2.png
api_postman_updatedetails3.png
  1. Navigate to the PUT v3/users/{id} endpoint.

  2. Enter the UserID as the value of the id param.

  3. On the Auth tab, select the token as in the previous step.

  4. Select the Headers tab.

  5. Deselect the Content-type check box because you do not want to send form data, but a JSON object.

  6. Select the Body tab.

  7. Select raw.

  8. Select JSON.

  9. Paste the JSON object of the user's data.

  10. Edit the data you want to change.

  11. Select Send.

  12. Note the return code 200 OK.