In the previous blog post, I explored how to connect to the Tableau PostgreSQL port 8060 (a database that stores tableau server metadata) using Alteryx. I also went through some examples of why you would want to connect through Alteryx. For today’s blog, I wanted to focus on the general process to connect to the Tableau REST and Tableau Metadata API, and some of their use-cases to improve your overall knowledge of Tableau capabilities.
What is the Tableau REST API?
The Tableau REST API documentation can be found here. This functionality is available to Tableau Online, and Tableau Server 9.0 and later. To summarize, this API allows you to perform the normal functions that you would expect from REST:
GET: Access information, such as content lists or thumbnail.
POST: Creation of resources/information, such as workbooks or user
PUT: Update existing resources/information.
DELETE: Delete existing resources/information.
What is the Tableau Metadata API?
The Metadata API documentation can be found here. This functionality is similarly available to Tableau Online, and Tableau Server 2019.3 and later. To summarize, this API allows you to collect certain types of metadata which is more difficult or not available in other metadata sources, including SQL queries and calculated fields.
How is the REST and Metadata API Different?
While both are API’s, I have alluded to each of them having more specific use cases, but there are also technical differences between them:
Queries: The Tableau REST API can be queried using JSON or XML, and the tool is easy to parse using an XML Parse tool, however, the Metadata API uses GraphQL queries.
The Process of Connecting API’s in Alteryx
Step 1: Choose Your Authentication Method
As the information that you are accessing is secure, you must submit authentication as a Payload in the download tool. This will either be written in JSON or XML, but I prefer to construct this using the JSON Build Tool and using the notation of dots to represent the hierarchy. You can either choose to authenticate using a username and password, or you can choose to generate an access token and access secret (this being the preferred option for security). Within the body of this request, you must also specify the contentUrl, which is basically the name of the site which you want to access.
An example of the text input tool to construct this JSON body would be:
Field 1: Name Field 2: Value
credentials.personalAccessTokenName (Enter Name)
credentials.AccessTokenSecret (Enter Token Secret)
credentials.site.contentUrl (Enter Site Name)
Step 2: Build the Authentication URL String
Using the documentation, you will find the query of the URL string. It should look something like:
https://[Tableau Server Name] /api/3.8/auth/signin
To be clear, the number between the API and auth is representative of the tableau server version, and you can find a reference guide to that in the documentation. This means, if this workflow runs regularly, then you will need to update this URL string when you upgrade the server. Or you could try to download the documentation page and make it dynamic to the current tableau server version.
Step 3: Append and Configure Download Tool
Now that the authentication and URL string have been made, you can append these 2 text inputs, put the JSON Build if you have not already and place the download tool. Within the Basic configuration, select the URL field. Within the headers field, select add, and under name write Content-Type, and under Value place application/JSON if you followed my JSON steps, or put application/XML if you wrote XML in the body. Within the payload tab, select the POST HTTP action, click the radio button Take Query String/Body From Field, and place the JSON/XML in here.
If you have configured everything ok, you will receive the HTTP 200 OK message within the Download Headers output, but if not, you can troubleshoot with this code and the supporting text.
Step 4: Parse Authentication and Use API
Congratulations, you have set up the connection with the API. By using an XML Parse tool, you will be able to create the important field “token”, which I would re-name to “X-Tableau-Auth”. In subsequent API calls, you will need to use this field in the headers tab, and you will no longer need the payload or content-type header.
Step 5 (Optional): Build a Batch Macro
In subsequent downloads, you will be able to create queries such as https://[Server_Name] /api/3.8/sites/ to gain a list of sites. As the authentication is specific to the site that we specified, you could theoretically use the output of the previous request to get the authentication for all sites. This will be achieved through a batch macro as Tableau supports logging into 1 site at a time. What the batch macro will do is run each of the sites and union the data together. There are many blogs that explain how to build a batch macro, such as Alex (from DSAU5).
Conclusion:
The Tableau PostgreSQL from Part 1 has many great benefits to collecting and accessing metadata, but it is not the only source to collect information. The API’s that Tableau have are just as important as the database, both for analysis and other activities.
