API Overview

Every element of the stacuity platform can be configured and controlled using the API. The stacuity portal uses this API - so anything that can be achieved with the portal can be achieved from other systems. This allows for tight integration and powerful automation of stacuity functions.

The API is based on REST - and all the methods and operations are described in the Reference Documentation.

In order to use the API, it is necessary to generate an API token, which is used as Bearer Token. The easiest way to generate an API token is to log in to the portal and choose 'Access Control / API Tokens'.

Tokens are specific to a customer - and by default, the token generated will have access to the same functionality as the user account used to create it.

The token has been generated (32 hex characters), copy it to the clipboard before closing the window or navigating away. Previously generated tokens cannot be subsequently retrieved.

Tokens can be tested by using Curl or similar - by calling the token verification API - replacing the 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' with the API token generated.

curl -X GET "https://api.stacuity.com/api/v1/apitokens/verify" -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "Content-Type:application/json"

If all is well, the response should be:

{"success":true,"messages":["Congratulations, your API Token works."]}

This shows the common format of most stacuity API calls - an outer block of JSON indicating whether the operation was successful, optionally an array of messages (useful if the operation fails), and optionally a 'data' block containing any results.

As an example, consider the API to retrieve the details of a particular VSlice (documented here). On success, the data retrieved using this method is as follows:

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Default",
    "moniker": "default",
    "subnets": [
      "100.64.0.0/10"
    ],
    "dnsServers": null,
    "dnsMode": {
      "key": 10,
      "moniker": "auto",
      "name": "Auto"
    },
    "ipAddressFamily": {
      "key": 4,
      "moniker": "ipv4",
      "name": "IPv4"
    },
    "endpointGroupCount": 1,
    "endpointCount": 0
  },
  "success": true,
  "messages": []
}

The 'success' value is 'true', there are no messages, and the 'data' value contains a JSON representation of the VSlice (plus associated data).

Identifying objects

All objects within the stacuity platform have a unique ID - normally a GUID. This can be used as the identifier when using the API, but if you have assigned a moniker, then this can be used as a convenient alternative.