Scalr API

To start, an API token must be generated by clicking on your user on the top right of the screen and click on “API Access”:

../_images/api_access.png

This can be done in the account or an environment.

This will provide you with an ID and token. The token will disappear after you click close so make sure to copy it before closing the window.

Authentication

Requests to the API are authenticated with a bearer token using the HTTP header Authorization: Bearer <token>.

If the token is not supplied or it is invalid, Scalr returns the status response HTTP 401 Unauthorized and a JSON API error object. Status response 401 is only used when there are problems with the authentication token. If the token is valid but the requester does not have the required permissions for the endpoint/method then Scalr will return the status response HTTP 404 Not found.

API Versioning and Path

The Scalr API has the current major version “v3” with a path prefix of /api/iacp/v3

If there is a future change to API semantics the version will increment to “v4”.

API Profiles

The API has the following profiles available to enable implementation and deprecation of features in a controlled and predictable manner:

  • preview: Experimental functionality for end users. Available in the public OpenAPI specification. Features in this profile are considered “beta”. API interfaces might change between on-prem feature releases, or at any time on Hosted Scalr. Customers should only use preview in non-critical workflows in order to test and provide feedback. Features from the “preview” profile might be promoted to stable or may be dropped.

  • stable: The API mainline. It is the default profile for all API clients. This profile is highly backward compatible between two feature releases, and the process of deprecating features is described below. When it is decided to remove a stable feature from the API the feature must be first moved into to the “deprecated” profile.

  • deprecated: The profile were features are retiring, before their removal from the API. Features can move into this profile from the “stable”, and the API interface remains untouched until removal from the product.

The profile is set using the header Prefer: option as show in this example.

curl -s -X ${HTTP_OP} ${API_URL}${THE_PATH} \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/vnd.api+json" \
      -H "Prefer: profile=preview" \
            --data "@data.json"

API Feature Deprecation

scalr.io (SaaS)

Any deprecation will be communicated through the API specification, documentation and HTTP API responses.

  • preview: Feature removal will be communicated 2 weeks in advance.

  • stable: Features planned for deprecation will remain in stable profile for 3 months after the announcement of planned deprecation. After 3 months the feature will be moved into the deprecated profile.

  • deprecated: After the feature is moved into the deprecated profile, it is will be available for use for at least 3 more months.

On-Prem Scalr

Any deprecation of API features in Scalr release packages for on-prem will be communicated via Scalr release notes as well as through the API specification, documentation and HTTP API responses.

Functionality could be deprecated both in major and minor releases, but cannot be deprecated in a bug fix release. The term “feature release” within the next few sentences is equal to major or minor based on semantic versioning.

  • preview: Functionality could be dropped form a next feature release with the release notes communication only.

  • stable: Features planned for deprecation will remain in the stable profile at least until the next feature release, after which this functionality will move to the deprecated profile.

  • deprecated: After the feature is moved into the deprecated profile, it will be available for use until at least until the next feature release.

API Format

The Scalr API is a REST API. It follows JSON:API v1.0 semantics for requests and responses.

JSON API Responses and Inputs

Responses from the API will be JSON Documents.

For POST and PATCH methods a JSON API document is required as the request payload. This is an example of payload to create a workspace.

{
    "data": {
        "attributes": {
            "auto-apply": true,
            "name": "workspace-name",
            "operations": true,
            "tags": [
                {
                    "name": "tag-name",
                    "value": "tag-value"
                }
            ],
            "terraform-version": "0.12.28",
            "vcs-repo": {
                "branch": "master",
                "identifier": "vcs-xxxxxxxxx"
            },
            "working-directory": "sub-dir"
        },
        "type": "workspaces"
    }
}

The JSON must be structured as follows

  • Top level data property.

  • data.type property as defined in the API method specification.

  • Typically will include data.attributes containing the attributes of the object with possibly other nested objects.

The documentation will reference nested attributes using the format shown in this example.

{
    "data": {
        "attributes": {
            "auto-apply": true
        }
    }
}

referenced as data.attributes.auto-apply.

Method Parameters

For some POST, PATCH and DELETE methods it is necessary to specify the relevant object ID as part of the endpoint path. This may be the only parameter or may also require a JSON object to be passed as well. The object ID place holder will be shown using {...} notation as shown in this example.

POST /api/iacp/v3/workspaces/{workspace}/actions/unlock

For GET methods it may be necessary to pass in query parameters such as filters, using the ?filter[attribute]=value format. Depending on the tooling, it may also be necessary to encode the [] using %5B and %5D. The documentation assumes the encoding is required and describes the method as shown in this example.

GET /api/iacp/v3/runs?filter%5Bworkspace%5D=string HTTP/1.1

The “parameters” section for each method describes the query parameters for the method and specifies which ones are required and which are optional. See below for details on using the pagination parameters.

Pagination Parameters

Pagination is supported for any method that returns an array of objects. The default is to return the first 20 objects but this can be altered by specifying a page number and size as parameters to the query in the following format.

...?page[number]=3&page[size]=25

This example would return objects from number 51 to 75 (if these exist).

The links and meta attributes will contain pagination data to make it easy to re-query the API for additional objects.

{
    "links": {
        "first": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "last": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "next": null,
        "prev": null,
        "self": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20"
    },
    "meta": {
        "pagination": {
        "current-page": 1,
        "next-page": null,
        "prev-page": null,
        "total-count": 2,
        "total-pages": 1
        }
    }
}

Example Usage

Below is the syntax required to make an API call in shell script using curl

curl -s -X ${HTTP_OP} ${API_URL}${THE_PATH} \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/vnd.api+json" \
      -H "Prefer: profile=preview" \
            --data "@data.json"

This is an example of what a complete call to create a workspace might look like.

curl -s -X POST HTTPS://my-account.scalr.io/api/iacp/v3/workspaces \
      -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/vnd.api+json" \
      -H "Prefer: profile=preview" \
            --data "@create-workspace.json"

This is an example of the data required for a workspace bound to a VCS.

 {
    "data": {
        "attributes": {
            "auto-apply": true,
            "name": "example",
            "queue-all-runs": true,
            "terraform-version": "0.13.5",
            "vcs-repo": {
                "branch": "master",
                "identifier": "scalr-eap/vcs-example",
            }
        },
        "relationships": {
            "environment": {
                "data": {
                   "id": "env-t2fcrq6h1v3nf0g",
                   "type": "environments"
                }
            },
            "vcs-provider": {
                "data": {
                   "id": "vcs-82d594bacd10",
                   "type": "vcs-providers"
                }
            }
        },
        "type": "workspaces"
    }
}

API Profile Specifications