API troubleshooting

This article contains tips for troubleshooting requests to the Skytap REST API.

Tips for new API users trying to get any request to work

If you’re having trouble making any successful API requests, try a simple request to a resource collection to help narrow down whether the issue is with the authentication or request formatting.

For example, try making a GET request to https://cloud.skytap.com/configurations. Any Skytap user should be able to successfully send this request.

A successful request is indicated by a 200 HTTP status code in the response header. If you don’t own any environments, the response body may be blank.

If you’re unable to complete the above request:

  • Make sure you’re using an API security token instead of your password (if API tokens have been enabled in your account). For more information about how to check whether API security tokens are enabled in your account, see API Authorization.
  • Confirm that you’re using the correct user name and API token (or user name and password).
  • Make sure that your tool or programming library supports TLS v1.2. Skytap doesn’t support TLS v1.0 or v1.1.

    For example, in PowerShell scripts, add [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 to enable TLS v1.2 for your session.

  • Make sure that you’ve included all of the required headers. See Required headers for API requests.

Tips for troubleshooting problems with specific API requests

If you’re having trouble with a specific API request, check the HTTP status code and response body for more information.

Generally, most issues are caused by:

  • Permissions. If you’re a standard user, you can’t perform actions reserved for administrators or on resources that you don’t have access to. When troubleshooting, attempt to perform the same action using the Skytap web interface.
  • An improperly formatted query string or response body. Use the API v1 reference and API v2 reference to check the syntax of a request.
  • Trying to complete an action on a busy resource. For more information, see API best practice: Checking for busyness.
  • A missing request header. For more information, see Required headers for API requests.

Best practice: Checking the status of a resource

An API request may return a 200 HTTP status code, even if the operation can’t succeed due to an error or because the resource is busy. A 200 status code indicates that the authentication was successful and the request was properly formatted; however, it doesn’t indicate a completed update to the resource. Your script should check for both a 200 status code and an indication that the change was successfully made.

For more information about checking for the successful completion of an operation, see API best practice: Checking for busyness.

Some resources (like environments) have an error field that is populated when there is an problem with the resource (for example, if the VM can’t perform an operation because VMware Tools is still loading or if an import job failed because it contained an unsupported VM type). Generally, these error messages linger until the next successful state change, regardless of whether the issue still persists.