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.

  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

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.

1. Get your Documentation URL. Note the double backslash after "webapi".
   Example: http://localhost/webapi//swagger/docs/3.

   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.

2. View any API endpoint.
3. Select the red exclamation point to the right to start the authentication process. 
4. Copy the Token URL. Example: http://localhost/webapi/oauth2/token.

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.
   
   
   

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 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.
   

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

5. Set Token Name to YOUR_TOKEN_NAME. 

   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.
    

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 

• Make a general query to get an ID
• Use the ID to get detailed data
• Use that detailed data to change a piece of the data and update the record

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.

Step 1: Get a UserID from a List of Users

1. Navigate to GET v3/users.
2. Deselect 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. 
   

Step 2: Get the User's Detailed Information

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

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. 

Step 3: Update the User's Record

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

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.