Skytap API quick start

This quick start guide provides the basic information you need to begin making valid Skytap API requests. This guide assumes that you have a general understanding of REST APIs and API clients.

Contents

Skytap resource URLs and supported operations

Generally, each Skytap component (environment, user, project, etc.) has an API resource hosted at https://cloud.skytap.com.

API resources can respond to GET, POST, PUT, and DELETE HTTP requests.

The supported HTTP requests will vary by resource type.

For example, to request information about all of the users within your Skytap account, make a GET request to the Users resource collection:

GET https://cloud.skytap.com/users

To request information about a specific user, add the user's ID number to the request:

GET https://cloud.skytap.com/users/123

For a full list of available resources and supported operations, see the detailed documentation in API v1 reference and API v2 reference.

Required headers for API requests

Each API request must include an Authorization header and Accept header. PUT or POST requests with a request body must also include a Content-Type header. For example:

GET https://cloud.skytap.com/configurations
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

The table below contains additional information about these headers.

Header Description
Authorization header Skytap API requests must be made from a Skytap user or administrator account. When making a request, include a Basic Auth header with a base 64 encoding of either username and API token or your Skytap username and password, depending on your Skytap account settings:
  • If an API token is listed on your My Account page in Skytap (https://cloud.skytap.com/account), you must authenticate with the base64 encoding of your username and API token (username:api-token).
  • If an API token is not available, you must authenticate with your username and password (username:password).

Alternately, see Requesting your API token from the API.

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Tips

  • We recommend using API tokens instead of passwords.
  • Do not store usernames and passwords in plain text.
Accept header

API requests must include an Accept header that indicates an accepted response format (either JSON or XML). JSON is strongly preferred.

Accept: application/json
Content-Type header

PUT or POST requests with a request body must include a Content-Type header describing the format of the request body (either JSON or XML). JSON is strongly preferred.

Content-Type: application/json

Passing data with request bodies and query strings

When making a PUT or POST request, you must include a request body OR use a query string to pass data to Skytap.

Example PUT request with a request body

PUT https://cloud.skytap.com/users/7
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
Content-Type: application/json

{
	"email": "alex@example.com"
}

Example PUT request with a query string

PUT https://cloud.skytap.com/users/7?email=alex@example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Sample API request and response

The following sample API request will return a list of templates the user has access to:

Sample request

GET https://cloud.skytap.com/templates
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Sample response

The API will return a response body with short representations of templates the user has access to:

[
    {
        "id": "123455",
        "url": "https://cloud.skytap.com/templates/123455",
        "name": "Sharepoint Server 2013",
        "region": "US-West",
        "region_backend": "skytap"
    },
    {
        "id": "123456",
        "url": "https://cloud.skytap.com/templates/123456",
        "name": "DevStack Single VM",
        "region": "APAC",
        "region_backend": "skytap"
    }
]

This information can be used to make additional API requests.

For example, to create an environment from one of these templates, make a POST request to https://cloud.skytap.com/configurations; include the ID number of the template you want to use.

POST https://cloud.skytap.com/configurations?template_id=123456
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

API permissions and security

Skytap API requests must be made from a Skytap user or administrator account.

Skytap users and administrators have the same permissions in the REST API as they do in the Skytap web interface. For example, administrators can view and create users or run usage and auditing reports, while standard users cannot. As in the web interface, users can view and manage the environments, templates, assets, and other resources that they own or have access to.

Often, if a user does not have permission to perform an operation or access a resource, the API returns a 404 Not found status. The API may also return a response body with following error message:

{
	"error": "You do not have sufficient privileges to perform this action"
}

API endpoints share the same URL and are secured by the same SSL certificate as the Skytap web interface (https://cloud.skytap.com).

HTTP status codes

The Skytap API uses HTTP standards for error and status reporting. This table contains some of the more common HTTP codes that you may encounter when using the API. We may also display additional information in the response body.

HTTP Status Code Meaning
200 Success
302 URL redirection
401 Unauthorized (Authentication is required, and has failed or not been provided)
404 Not found (Resource cannot be found, may be available in the future)
409 Conflict (Request is well-formed but conflicts with another resource or permission)
422 Invalid parameter (Request well-formed but contained semantic errors). Also used to indicate that a runstate change was attempted on a busy resource.
423 Resource is busy; please wait and try your request again shortly. For more information, see API best practice: Checking for busyness.
429 Too many HTTP requests in a given period of time
500 System error (Given when no specific error message is available)
For more information on the full range of HTTP status codes, see the Wikipedia List of HTTP status codes.

Error fields

Some resources contain "error" fields that provide more information about a problem with the resource (for example, if the VM cannot 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. For best practices that can help prevent errors, see API best practice: Checking for busyness.

Using the API with auto-suspend

By default, API GET requests on a VM or environment will be recognized as activity in the environment and will delay auto-suspend from taking effect.

The API includes an optional ?keep_idle=true parameter you can add to select API GET requests. This value will tell the auto-suspend timer to ignore the API request when determining whether the environment is still in use. This parameter can be added to three requests:

GET https://cloud.skytap.com/configurations/<config-id>

GET https://cloud.skytap.com/vms/<publish set id>/desktop

GET https://cloud.skytap.com/vms/<publish set id>/desktops

API versions

Skytap has two API versions, v1 and v2. Both versions of the API are supported and under development.

The v2 API introduces:

  • New versions of Skytap resources, including environments, templates, assets, users, and more.
  • New parameters that allow you to filter, sort, paginate, and adjust the scope of GET requests to select resource collections. For example, these new parameters allow you to request a representation of your users that is filtered by user role or a representation of your environments sorted by the date they were last run.

Note that:

  • The v2 API is not intended to replace the v1 API. In some cases, operations from the v1 API may not be available in the v2 API.
  • v2 representations of resources may contain different attributes than the v1 representations of these resources.
  • Depending on the resources, operations, and attributes that you work with, you may need to use both v1 and v2 of the API.

For detailed documentation about the resources in each version, see API v1 reference and API v2 reference.