Learn how to use the Avassa REST API with Postman

All Avassa operations are available over a REST API, see the reference documentation.

One way of learning the REST API is to use the popular Postman tool. Before continuing with this short how-to, please download the tool.

In order to get started there are two pre-conditions:

1. You need to know a bit about building the REST URIs
2. You need to authenticate your requests

REST URIs

The URI for the REST operations are primarily

1. First part is the API URL: When connecting to a Control Tower API, assuming your Control Tower is at https://my-env.acme.avassa.net, the API URL is https://api.my-env.acme.avassa.net. We will refer to this as the “API endpoint”, the api_ep variable, in the postman section below
2. The second part is the data model path, for example: v1/state/system/sites The data model paths are easily seen when navigating the data model in the reference documentation. You can also download the Avassa Open API specification and see the paths within Postman.

Another way of learning the above is to use the -v option to the Avassa Command Line tool which will display the endpoint and data model path.

$ supctl -v show system sites

...
GET /v1/state/system/sites
Host: [api.my-env.acme.avassa.net:443](<http://api.myenv.b2.avassa.net:443/>)

Authentication

As a user in Avassa you get tokens when accessing the system. It is a good start to create a local user in Control Tower before continuing. That user will be used to access your system over REST.

Create a user:

You can try login as that user using supctl:

$ supctl do login my-user@test.com
password:*************

And you will see the following output:

{
"token": "0c7ff93b-58ea-4d0b-a01c-ef774fa1176f",
"expires-in": 2764800,
"expires": "2022-12-04T13:38:11.019526Z",
"accessor": "6715a5dc-8d55-4bad-acf7-259571efd86d",
"creation-time": "2022-11-02T13:38:11.019526Z",
"renewal-time": "2022-11-02T13:38:11.019526Z"
}

The important thing to note is the token. Now you are well prepared to play with Postman.

Defining variables in Postman

In the Postman collection, select variables and create a variable called api_ep

Now we can access the API as https://{{api_ep}}/xxx

Login

Next create a login request

URL: https://{{api_ep}}/v1/login using POST Make sure you have selected JSON as Body format.

{
    "username": "my-user@test.com",
    "password": "secret pwd"
}

This call will return a payload like this, including the token.

In the test tab we also define a script to parse the token returned:

var token = pm.response.json().token;

pm.collectionVariables.set("token", token);

This javascript snippet will parse the token returned then store it in a variable called token.

Set authentication for requests

After running the Login request, we can use the token variable as bearer token in the following calls.

Create a new request, select Authentication and then Bearer token referring to the token as {{token}}.

Test the API

Now we can exercise the API, first let’s get the site status:

URL: https://{{api_ep}}/v1/state/system/site-status/sites using GET

Next, let’s create an application and an application deployment

URL: https://{{api_ep}}/v1/config/applications using POST

{
  "name": "popcorn-controller",
  "version": "1.0",
  "services": [
    {
      "name": "popcorn-controller-service",
      "mode": "replicated",
      "replicas": 1,
      "share-pid-namespace": false,
      "containers": [
        {
          "name": "kettle-popper-manager",
          "image": "registry.gitlab.com/avassa-public/movie-theaters-demo/kettle-popper-manager:v1.0",
          "container-log-size": "100 MB",
          "on-mounted-file-change": {
            "restart": true
          }
        }
      ]
    }
  ]
}

URL: https://{{api_ep}}/v1/config/application-deployments using POST

{
  "name": "popcorn-deployment",
  "application": "popcorn-controller",
  "application-version": "1.0",
  "placement": {
    "match-site-labels": "system/type = edge"
  }
}

Finally let us check the status of this application

URL: https://{{api_ep}}/v1/state/application-status/applications/popcorn-controller using GET

We can see that we have successfully deployed the application to a site called restaurant.