REST API Guide

In this guide you'll learn how to use the TSB REST API to perform common operations on the platform. The examples in this guide use curl, because it's a popular command used to perform HTTP requests, however, any tool that can do HTTP will work.

Authentication

TSB has two main authentication mechanisms: basic authentication and JWT token authentication.

Basic Auth

Basic HTTP authentication is done by sending the HTTP Authorization header with the credentials encoded in the header value. The basic format of the header is:

Authorization: Basic base64(username:password)

For example:

Authorization: Basic dGVzdDoxMjPCow==

JWT Token Auth

JWT Token authentication is header-based, and it's configured by setting a JWT token in the x-tetrate-token header. For example:

x-tetrate-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP verbs

The TSB REST API uses the common HTTP verbs to model all the operations that you can make on the different TSB resources:

• GET requests are used to get lists of resources or get the details of specific objects.
• POST requests are used to create new resources.
• PUT requests are used to modify existing resources.
• DELETE requests are used to delete resources and their children.

Example: common resource CRUD operations

The following examples show how to use the common CRUD operations on TSB resources using the REST API:

Resource creation

In this example, you'll create a tenant in an existing organization. You do this by sending the corresponding POST requests to the TSB rest API and using Basic Authentication:

$ curl -u username:password \
    https://tsbhost:8443/v2/organizations/myorg/tenants \
    -X POST -d@- <<EOF
{
    "name": "mytenant",
    "tenant": {
      "displayName": "My tenant",
      "description": "Tenant created using the TSB REST API"
    }
}
EOF

Output:

{"fqn":"organizations/myorg/tenants/mytenant","displayName":"My tenant","etag":"\"hhO8m7WN3LM=\"","description":"Tenant created using the TSB REST API"}

Modify a resource

Resources are modified by sending an updated object in a PUT request.

In order to update an object, you need to have the last copy of it. TSB has mechanisms to prevent concurrent updates and avoid conflicting versions of the same objects. To this end, TSB assigns an etag to every object and updates it every time the object is updated. It is mandatory to send the last etag for the object in PUT requests, to tell TSB that you are modifying the most recent version of the object.

In this example you'll:

✓ Send a GET request first, to get the last version of the object (updated with the latest etag).
✓ Locally modify the returned JSON.
✓ Send back the modified JSON document in a PUT request.

curl -u username:password \
    https://tsbhost:8443/v2/organizations/myorg/tenants/mytenant \
    -X GET | jq .

Output:

{
  "fqn": "organizations/myorg/tenants/mytenant",
  "displayName": "My tenant",
  "etag": "\"hhO8m7WN3LM=\"",
  "description": "Tenant created using the TSB REST API"
}

Modify the JSON document and send it back. It is important to keep the etag field:

curl -u username:password \
    https://tsbhost:8443/v2/organizations/myorg/tenants/mytenant \
    -X PUT -d@- <<EOF
{
  "fqn": "organizations/myorg/tenants/mytenant",
  "displayName": "My Modified tenant",
  "etag": "\"hhO8m7WN3LM=\"",
  "description": "Modified description"
}
EOF

Output:

{"fqn":"organizations/myorg/tenants/mytenant","displayName":"My Modified tenant","etag":"\"BhsObrdJUWI=\"","description":"Modified description"}

Delete a resource

Resources are deleted by sending the corresponding DELETE requests to the resource's URL. If a request is sent to a parent resource, then all child resources will be deleted as well.

curl -u username:password \
    https://tsbhost:8443/v2/organizations/myorg/tenants/mytenant \
    -X DELETE

Dry run mode

Dry run mode is a feature that allows you to simulate the execution of a process without making any actual changes. Dry run mode can be used with any POST, PUT, or DELETE request by adding the x-tetrate-dry-run: server-side header to the request.

$ curl -u username:password \
    https://tsbhost:8443/v2/organizations/myorg/tenants \
    -H "x-tetrate-dry-run: server-side" \
    -X POST -d@- <<EOF
{
    "name": "mytenant-dry-run",
    "tenant": {
      "displayName": "My tenant",
      "description": "Tenant created using the TSB REST API"
    }
}
EOF

Output:

{"fqn":"organizations/myorg/tenants/mytenant-dry-run","displayName":"My tenant","etag":"\"hhO8m7WN3LM=\"","description":"Tenant created using the TSB REST API"}

Even though the request was successful, the tenant was not created because the x-tetrate-dry-run: server-side header was added to the request. If try to get the mytenant-dry-run tenant using a GET request, it will return a 404 error.

curl -u username:password \
    https://tsbhost:8443/v2/organizations/myorg/tenants/mytenant-dry-run \
    -X GET | jq .

Output:

{
  "code": 5,
  "message": "resource not found",
  "details": [
    {
      "@type": "type.googleapis.com/google.protobuf.StringValue",
      "value": "computing an access decision: checking permissions [admin ([ReadTenant]) organizations/myorg/tenants/mytenant-dry-run]: target \"organizations/myorg/tenants/mytenant-dry-run\" does not exist: node not found"
    }
  ]
}