REST API quick start

This quick start guide provides the basic information you need to begin making valid Skytap REST 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, template, user, project, etc.) has an API resource hosted at https://cloud.skytap.com. Most of these resources can respond to GET, POST, PUT, and DELETE HTTP requests.

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 the full list of available resources and supported operations, see the detailed documentation at:

Required headers for API requests

Each API request must include an Authorization header and Accept header. 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.

Heading

Description

Authorization

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

When making a request, include a Basic Auth header with either your user name and API security token or your Skytap user name and password, depending on your Skytap account settings.

  • If an API security token is listed on your Account page in Skytap, you must authenticate with your user name and API token (<username>:<api-token>). For help, see Finding your user name and API security token.
  • If an API security token isn’t available, you must authenticate with your user name and password (username:password).

Basic Auth uses a base64-encoding of the <username>:<password> string (or <username>:<api-token> string). Many HTTP tools, clients, and programming libraries automatically perform the string encoding and header formatting for you. For more information about Basic Auth headers, see https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side.

Example:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Don’t store your user name and password in plain text.

Accept

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

Requests with a request body (typically PUT and POST requests) 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

Sending data with request bodies and query strings

To send data back to Skytap (generally in a PUT or POST request), you must either:

  • Include a request body.

    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"
  }

    or

  • Use a URL query string.

    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 returns a list of templates the user has access to:

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

The API returns:

  • A response header that includes an HTTP status code.
  • A response body with short representations of templates the user has access to.
Status: 200
Content-Type: application/json

[
    {
        "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-2",
        "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 can’t. 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 doesn’t 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).

Skytap supports TLS v1.2. If you can’t connect to the Skytap REST API, check whether your script libraries or modules use TLS v1.0 or v1.1 connections.

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

Using the API with automatic suspend or shut down

By default, API GET requests on a VM or environment will be recognized as activity in the environment and will delay an environment from automatically suspending or shutting down.

The API includes an optional ?keep_idle=true parameter you can add to select API GET requests. This value will tell the Skytap 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:

Both versions of the API are supported and under development. Note that:

  • The v2 API isn’t 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.

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.

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

Troubleshooting

For troubleshooting help, see API troubleshooting.

Copyright © 2024 Skytap, Inc. | Privacy Policy | Terms of Service | Support