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:
- You need to know a bit about building the REST URIs
- You need to authenticate your requests
REST URIs
The URI for the REST operations are primarily
- 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 ishttps://api.my-env.acme.avassa.net
. We will refer to this as the āAPI endpointā, theapi_ep
variable, in the postman section below - 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
.
Try iT yourself
Request a free trial
Deploy your first container application across a distributed edge cloud. Request your free trial now to explore our solution!