Testing and Troubleshooting REST API Calls


Usually, you make REST API calls to Tableau Server by writing a program in Python, Ruby, Java, C#, or other programming language that supports HTTP requests. However, if you just want to experiment with API calls, you can quickly make REST calls using various tools that let you set the HTTP header and body values, issue a request, and then see the results.

Using command-line utilities to test

Another option for testing REST API calls is to make requests using a tool like cURL(Link opens in a new window) or Wget(Link opens in a new window). The following example shows a cURL command that signs in to the server. The command requires you to pass XML information in the body of the request. An easy way to pass XML is to create it in a text file and then reference the text file in the cURL command by using the -d option. You can specify the HTTP verb (GET, POST, PUT, DELETE, etc.) by using the -X option.

curl https://MY-SERVER/api/3.22/auth/signin -X POST -d @signin.xml

The following is the content of the sigin.xml file that's referenced by the -d option:

<tsRequest>
  <credentials name="admin" password="Passw0rd" >
    <site contentUrl="MarketingSite" />
  </credentials>
</tsRequest>

The return values for requests that you issue at the command line are displayed on the command line. If you want to capture the output, you can typically redirect the command to a file, as in the following example:

curl https://MY-SERVER/api/3.22/auth/signin -X POST -d @signin.xml > restapi-output.txt

Most Tableau Server REST API requests require a header named X-Tableau-Auth that includes the authentication token that’s returned by a call to the Sign In method. Command-line utilities typically let you set header values for the request. The following example shows a cURL command that gets a list of users from a site. The command includes a value for the X-Tableau-Auth header, which you pass using the -H option.

curl http://MY-SERVER/api/3.22/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d/users/ -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Using browser-based options to test

You can also test REST calls by using add-ins or extensions in your browser. Some popular apps for testing REST APIs in Google Chrome are Postman(Link opens in a new window), Advanced REST client(Link opens in a new window), and Rest Web Service Client(Link opens in a new window). For Mozilla Firefox there are REST Client(Link opens in a new window) and REST Easy(Link opens in a new window). (Check the app store for your browser to find testing tools.)

Important: Some websites, such as hackst.com and apigee.com, allow you to issue REST API requests for testing. These will work for your Tableau Server testing only if your server is accessible publicly. If you do use a website to test REST APIs, be aware that you are posting potentially sensitive information to a public site.

Browser-based REST clients typically let you use a form to enter a URI, XML for the body, and header values. When you send the request, the results are displayed in a pane in the browser. The following illustration shows a session of a browser-based REST tool where a user has made a request using the Sign In method and has gotten a response from the server.

 

Using desktop options to test

You can also test REST API methods using desktop applications. One choice is RESTClient(Link opens in a new window), which is written in Java and works on multiple platforms.

Troubleshooting

If REST API calls are not working the way you expect, you can troubleshoot them several ways.

Examine error codes

If an error occurs during a request, the response includes both an HTTP status code (like 400, 403, or 404) and an <error> element in the response body. The <error> tag includes an error code that provides detailed information about the error. For information about errors, see Handling Errors in the REST API . The documentation for individual methods in the API lists the error codes that a method might return.

Examine requests and responses

It can be particularly helpful for troubleshooting to examine the raw requests that go between your client and the server. By examining the contents of each request (the HTTP verb and URI, the headers, and the request and response bodies) and comparing those to the documentation, you can often determine why a REST method is not working as it should.

For Windows, you can use Fiddler(Link opens in a new window), which is a web proxy tool that lets you examine and edit web requests. A similar tool is Charles HTTP proxy(Link opens in a new window), which works on Windows, OS X, and Linux. Other tools include:

Examine log files

Requests that you make to Tableau Server using the REST API result in log file entries on the server. You can examine the following log files to help troubleshoot REST API issues:

  • log-file-location\httpd\access.date-time-stamp.log (for example, access.2015_05_11_00_00_00.log).
  • log-file-location\logs\vizportal\vizportal-process-number.log (for example vizportal-0.log)

For information about how to generate a snapshot of log files, see Archive Log Files(Link opens in a new window). To learn more about log file locations, see Server Log File Locations.


Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!