Getting started with the Turbonomic REST API

Edit online

The easiest way to see results with the API is to try calls in the Swagger UI. To use the Swagger UI, navigate to:

https://<Your_Turbonomic_URL>/apidoc

You can use the Swagger UI to navigate to different endpoints and try out their methods. For example, if you navigate to the Users endpoint you can get a listing of all the users that are specified for your Turbonomic installation. For more information, see Turbonomic REST API Swagger Documentation.

Ultimately, you will want to implement scripts that use the API to get data, execute actions, or integrate Turbonomic with other processes. As you work with the API, you need to know about:

  • Authentication

  • URI Structure

  • Response Format

  • Time in the Turbonomic API

Authentication

To use the API, you must have a valid user account on the Turbonomic instance. Also note that accounts can have different roles. The API will only execute commands that are valid for your user role. For example, to execute Turbonomic recommended actions, your account must have a role of either administrator, deployer, or automator.

To make API calls, you request an authentication token and pass it with each call to the Turbonomic API. The token request returns a cookie for your authentication. A common way to use this token is to store the cookie locally, and pass it with your API calls.

Example: curl -s -k -c /tmp/cookies -H 'accept: application/json' 'https://localhost/api/v3/login?hateoas=true' -d 'username={your_username}&password={your_password}'

Then, each request must use the -b cookie-filename parameter to use the session cookie delivered by the login request.

Another approach is to get the authentication header and parse out the authentication cookie. Then you can create a header for each API request that includes the cookie. For example, assume you store the value in a variable named token. You could use it like this:

headers = {'cookie': token}
r = requests.get('https://10.10.123.456/api/v3/targets/specs', headers=headers, verify=False, stream=True)
Note: For a more complete explanation, see the Authentication Recipe in the API Cookbook.

URI structure

To use the Turbonomic REST API, your client will make HTTP requests to specific REST resources. The Turbonomic REST API supports the standard HTTP methods:

  • GET

    Get lists of entities or data objects, get individual items.

  • POST

    Create new objects in the Turbonomic environment, or specify filters for certain queries.

  • PUT

    Incrementally modify existing entities or objects.

  • DELETE

    Delete entities or objects.

The base URI structure for a Turbonomic REST API resource is:


        https://<Your_Turbonomic_URL>/api/<API_version>/<resource_name>

For example, to list the users in your installation:

https://111.222.33.44/api/v3/users

Response format

The Turbonomic REST API returns data as JSON objects. Turbonomic refers to these objects as Data Transfer Objetcs or DTOs. A DTO is an array of key-value pairs that describe the data you have requested, or the data that is the result of executing a POST or PUT. For example, if you GET the users defined for an installation of Turbonomic, the API returns a DTO similar to this:


[
  {
  "links": [
    {
      "rel": "self",
      "href": "https://10.10.10.10/api/v3/users/_4T_7kwY-Ed-WUKbEYSVIDw"
    }
  ],
  "uuid": "_4T_7kwY-Ed-WUKbEYSVIDw",
  "displayName": "Administrator User",
  "username": "administrator",
  "roleUuid": "_4UAioQY-Ed-WUKbEYSVIDw",
  "roleName": "administrator",
  "loginProvider": "Local",
  "type": "DedicatedCustomer",
  "showSharedUserSC": false
  }
]

In this case, the DTO is an array of one object. In other words, there is only one user accout defined for this installation of Turbonomic. The user object begins with a links array that gives the URL to this user account. It then follows with properties to describe the given user account.

Note that in most cases to execute a PUT or POST, you will pass the parameters to create the object via a DTO. These DTOs are similar to the associated response DTOs, but they are not identical. For this example of a user account, the response DTO does not include the user account password, but the DTO to create an account must include the password.

You can try out different REST methods in the Swagger UI to see typical response DTOs.

Time in the Turbonomic API

The Turbonomic REST API contains requests that require a start time and/or an end time to create or filter information. Time may be entered in three different formats:

  • ISO 8601 Date and Time Format

    YYYY-MM-DDTHH:MM:SS. For example, 2018-10-07T12:38:17

  • Epoch Time

    Epoch Time is represented as the number of seconds that have elapsed since midnight UTC, January 1, 1970. For example, 1514764800 corresponds to January 1, 2018 12:00:00 AM UTC.

  • Relative time

    Relative time is represented as the time relative to when the call is executed. For example, a start time of -1w and an end time of -1d indicates that the results should include entries from a week before the call is executed, to the day before the call is executed. Relative units are case-sensitive. Turbonomic supports the following relative units:

    • m — minutes

    • h — hours

    • d — days

    • w — weeks

    • M — months

    • y — years

Pagination in the Turbonomic API

Some API calls return very large datasets. Turbonomic recommends using the pagination features at all times. This is particularly important for larger environments managed by Turbonomic. Via scopes and filters for individual requests, data may be preliminarily filtered. Using the limit and x-next-cursor parameters, the data can be returned in manageable chunks.

For example:

https://10.10.10.10/api/v3/markets/214075923753936/entities/stats?limit=5&ascending=true

The previous request is to obtain statistics for all entities in a specific market. limit=5 indicates that each page of returned data should have 5 results.

The headers in the returned data will now include x-next-cursor: 5. In order to retrieve the next page of results, use the cursor in the next request:

https://10.10.10.10/api/v3/markets/214075923753936/entities/stats?cursor=5&limit=5&ascending=true

When the final page is reached, the x-next-cursor will be empty.

Note: Cursor is a string and should not be interpreted by a user. Different API endpoints might have different string cursors formats. The format of a particular endpoint's cursor might even change over time. This is necessary to achieve certain efficiencies in the sort and filtering of results.

If a request features the orderBy, limit, or cursor parameters, using one of those parameters will return paginated results.