v2.5 Postman quick start guide using token auth

This article shows how to quickly get started using the QUX v2.5 API using token authentication and the Postman API testing tool.

Introduction

Vectra uses RESTful APIs. In this article, we will use the "/health" API endpoint as an example from the APIv.2.5 documentation which can downloaded from https://support.vectra.ai/s/article/KB-VS-1638.

If you would prefer to use OAuth2 to access the v2.x Quadrant UX APIs, that is supported starting in v9.1. Please see REST API Quick Start Guide for Postman v2.5 using OAuth2 (QUX).

A note on API version

There are a few versions of API documentation available for Vectra users and every version of the API documentation enhances the previous version as new features gets released on Vectra platform. Browse to https://support.vectra.ai/s/ and search for "API", which will list all the available versions of the API documentation. In this article we will use the APIv.2.5

Postman Terminology

1. Request:

A http request using a http method such as GET, POST, PUT. PATCH etc.

2. Collection

A bunch of requests grouped together allowing to take action such as sending the request either individually or as a bunch

3. Variables:

Removes repeated typing of texts such as say for example a base URL for an API endpoint. Variables have various scope available in Postman and two scopes that are of interest to us are "Collection" and "Environment" scope. usage of variables is not described in this article, and instead, we will have them discussed in detail in an upcoming Youtube video whose link will be added at the end of this article once available.

Inception

Postman can be downloaded from https://www.postman.com/downloads/ for free and then change to the cool Dark theme by clicking Gear icon > settings > select "Dark Theme".

API Key

In order to perform an API query we need to pass an "Authorization" token in our request header which can be obtained by going to "Profile > View/Generate API Token" from the Brain UI.

Permission specific to "/health" endpoint

As per the API documentation please note that the health API requires the** "view health"** permission to access the system health data via API.

Sending a Request

Let's use the previously obtained API token to make our first request to "/health" endpoint.

1. Click on "+" to start an new request 2. Then select the http method to "GET"

2. Enter the URL of the API endpoint(https://<Vectra Mgmt IP>/api/v2.5/health)

3. Go to "Headers" section of the current request and then enter key="Authorization" Value="Token <Token obtained from the UI>"

4. Click send

5. Now if all the above information is correct and there is connectivity from your PC to Brain and the "view health" permission is available for your role, we should see a response for that endpoint 7. We can then save this request as part of a new collection by clicking on "save"

6. Continuing from step 7 and as shown below you can either pick an existing collection or select an existing collection from the available list to save this request, we will change the request name to "all_health" and then add to a collection "Test"

7. Similarly as you can see from the below screenshot that I have created a few more requests for say "/health/system" and "/health/network" and named those requests appropriately and added them to collection "Test"

Running a Collection

Let us now run our "Test" collection by going to "Collections > Clicking on 'Test' > Run", this will open a Runner tab as shown below

From the runner tab we select "Run Manually" and then click "Run Test", this allows us to run all the requests within that collection making it easier for us. Th

Notice below we get "401 unauthorized" for both "health/network" , "health/system" and "200" for "all_health" request. If you remember we need "Authorization" token for every request. we added the "Authorization" header when we created our "all_health" request but we did not do the same to our "network and system" request.

Imagine having say 15 requests and now you need to add the "Authorization" which is cumbersome. We can avoid this by performing the below 2 steps

1. Navigate to collection itself, defining the API key/Value and making sure to select "Add to Header" as shown below

2. In the "Authorization" section of the existing and/or a new request make sure the "Type=Inherit auth from parent". Now when we re-run the collection we can see "200" as the status response for both "network" and "system" elements of the health endpoint

Youtube

You can also watch a walkthrough of our support engineer using Postman to perform API queries by visiting the below link to Youtube.

https://www.youtube.com/watch?v=mKsDPCES_2g