Tableau REST API Postman Collection

Overview

This repository contains an open source collection of Postman requests for each method in the Tableau REST API surface.

• How to use the collection
• How to contribute to the collection (in the Postman app)
• View or add issues (in this repo)
• Advanced usage

About the repository: This GitHub repository is only used for issue tracking. Use Tableau APIs Postman in the Salesforce Developers workspaceto get the latest versions of the collection and environment files for your own use. The collection and environment files are hosted on Postman and synchronized to this repository for source control.

About the Tableau REST API: The Tableau REST API enables you to perform many of the actions available through the Tableau UI programmatically in scripts, terminals and applications. Resources you might find useful:

• For detailed descriptions of each method read the REST API reference.
• Join the Tableau Developer Program (includes a free Tableau sandbox and an invitation to join the #DataDev workspace on Slack!).
• Slack with REST API creators and users on Tableau #Datadev #help-rest-api.
• Interact with fellow devs in the Tableau REST API Community Forum.

About this collection: The preformatted requests in this collection allow you to discover and make calls for each method in the REST API to your Tableau Cloud site or Tableau Server. You can use it to make small administrative changes, prototype the request for your script, see a real example of the response for your request, and more.

The collection has also been enhanced with scripts and environment variables to make it easier to use.

How to use the collection

To get started, follow these three steps:

1. In Postman: Fork the collection itself.
2. In Postman: Fork the environment variables for the collection.
3. In your fork: Declare values for variables.

Once you have completed these steps you are ready to send requests to your Tableau environment!

Check out Advanced Usage for more additional tips and Who to Thank to find the original authors of this collection.

Step 1: Fork the Tableau REST API collection

1. Go to the Tableau REST API collection in the Salesforce Developer's Postman workspace in a browser.

2. Sign in to or create a free Postman account.

3. Choose the three dots next to Tableau REST API to view more actions.

4. Choose Create a fork.

5. Name the fork and the Postman workspace you want it to live in.

6. Keep the Watch original collection checkbox selected to be alerted whenever updates are available to the collection.

7. Choose Fork collection.

   At this point you should see the collection in your Postman workspace.

Step 2: Fork the environment variables for the collection

1. Go to the Environments section of the the Salesforce Postman workspace .

2. Choose the three dots next to Tableau REST API Environment to view more actions.

3. Choose Create a fork.

4. Name the fork.

5. Make sure to use the same Postman workspace you used for the collection.

6. Choose Fork environment.

   Now you should see the Tableau REST API Environment environment variables in your Postman workspace.

7. (Optional) Choose the three dots next to the forked environment and rename it to differentiate it from the original.

   This way, if you want to set up multiple environments for different Tableau servers or sites, you can duplicate the original environment variables and customize credentials and other values per environment.

Step 3: Declare values for variables

To configure the collection for your Tableau environment:

1. Go to the Environment Variable section of Postman and open the Tableau REST API Environment file.

   NOTE: You can duplicate your fork to declare environment variables for different Tableau sites and servers. That way each set of environment variables can be saved for later use.

   

2. For the server variable value, enter the domain of your Tableau service into the CURRENT VALUE field. For instance:

   myserver.example.com
   

   or

   10ay.online.tableau.com
   

3. Determine the authentication method you wish to use and declare the CURRENT VALUE for those fields in the environment file. To understand how credentials impact the responses to obtain from Tableau's REST API, see Tableau authentication credentials and permissions.

4. Modify content-url, the permanent name of a Tableau site. The content-url in the following examples is "mySite":

   http://myServer.com/#/site/mySite/
   
   https://10ay.online.tableau.com/#/site/mySite
   

5. Set api-version to match the version of the REST API that you wish to use (see REST API versioning).

6. Save your changes.

7. Modify the Environment in the top right corner to your environment variables.

8. Authenticate by running a sign in request and BOOM!, you are ready to use the collection.

   See Automatic Authentication to skip manual sign in.

To learn more about using the REST API, try the Get Started Tutorial in the API reference.

Advanced usage

• Update your forks
• Tableau authentication credentials and permissions
• Automatic Authentication
• Set environment variables from response values
• Credentials token, site-id, and auto-auth

Update your forks

To update your collection forks, select the three dots next to the collection name, and then select Pull changes.

Tableau authentication credentials and permissions

Tableau credentials are mapped to individual users which enforce access controls and permissions defined in your Tableau environment. This means that certain methods are only available to admin users and API responses will only contain data that the given user has access to.

A detailed description of authentication methods can be found in the Authentication section of the API Reference. Authentication methods include Username & Password, Personal Access Token (PAT), and JWT (Connected Apps).

To understand how credentials are kept safe within Postman, refer to the documentation on initial and current variables as well as variable types.

You can use credentials for an admin user to get broad access to API methods and the resources they touch. That kind of access is reduced for Users with lesser permissions. To test granted permissions or troubleshoot a user's problem, an admin can impersonate other users when needed.

This table shows the types of authentication supported in REST API requests.

CREDENTIAL	VARIABLES (Administrator , Impersonated User)
Username & Password	admin-username , user-username
	admin-password , user-password
Personal Access Token (PAT)	admin-PAT-name , user-PAT-name
	admin-PAT-secret , user-PAT-secret
Connected Apps (JWT)	JWT (scoped access via app code)

Automatic Authentication

To authenticate yourself in Tableau manually, you can choose and use one of the authentication methods that matches the credential type(s) that you have configured in your environment variables. You can also configure the collection to skip manual authentication and automatically authenticate when you make a request.

To turn on auto authentication, choose the Tableau REST API Collection in Postman at the top level, and then choose the Variables tab, and set the current value of auto-auth to true.

NOTE: If more than one type of credentials are configured in your environment variables, the type used by automatic authientication is not predictable. For instance, if valid credentials for both an administrator and a user to be impersonated are configured, the user that gets validated last will be the one signed in. Likewise, if PAT and username/password credentails are configured, the type of configuration used to sign in can't be predicted. If you need to control the sign in method, we recommend using manual sign in, or only configuring a single set of credentials in your environment variables.

Set environment variables from response values

Postman allows you to right-click on the returned value in a request's response body and assign that value to an environment value. This is helpful because a common action is to make an initial request in order to obtain the ID or name of a resource (workbook, user, datasource, etc.) in order to use that value in a subsequent request to the REST API.

This collection supplies a comprehensive list of variables for each Tableau resource type. Those variables are also formatted in the URI paths for each request. This means that using an ID or name from a response in the next request is quick, easy, and much less bug prone than copy pasting said values.

Credentials token, site-id, and auto-auth

In order to use Tableau's REST API effectively, it is very important to understand how authentication works as responses from the API will differ based on the user credentials used to establish a session to send requests. The 'Concepts' section of Tableau's API reference states the following Signing In and Signing Out (Authentication):

The Tableau Server REST API requires that you send a credentials token with each request. The credentials token lets the server verify you as a valid, signed in user. To get a token, you call Sign In and pass credentials of a valid user, either a Personal Access Token (PAT), a user name and password, along with the content URL (subpath) of the site you are signing in to. A subset of Tableau REST methods support sign in using a JSON Web Token (JWT), typically generated by a Tableau connected app.

In other words, your first request should aim to establish a new session using a set of credentials. Subsequent requests to Tableau require an X-Tableau-Auth header containing the API key or token as it's value. The API key is obtain as a successful response to a sign in method.

This Postman collection will automatically use new API keys (by storing them as the api-key variable) each time a response is received from the API containing a new session. This means that you should never need to worry about setting the X-Tableau-Auth header yourself since manual requests to a "Sign In" method or automatic authentication via auto-auth will already do this for you.

For security purposes the API key or session will expire and needs to be refreshed for continued use. When auto-auth is true, a script that performs the sign in flow runs before each request, ensuring that the token value is always valid. When auto-auth is false, you will need to manually sign in to refresh the token value.

How to contribute to the collection

This collection is open source and we welcome your contributions!

Contributions usually come in the form of enhancements to Postman files or documentation via pull requests as well as by reporting bugs as issues.

For more information, please refer to CONTRIBUTING.md.

About the repository: This GitHub repository is only used for issue tracking. Use Salesforce Developer's Postman workspace to get the latest versions of the collection and environment files for your own use. The collection and environment files are hosted on Postman and synchronized to this repository for source control. For more information, see the How to Use the Collection section.

Who to thank

The Tableau Postman collection is a gift to the Tableau community from three of Tableau's great Solutions Engineers: Stephen Price, Jeremy Mayo, and Alex Cortez.

Made with contrib.rocks.