Integrate NetQ API with Your Applications

1. Download Swagger UI 2.0.

2. Open a new browser tab or window, and enter one of the following in the address bar:

   • Cloud deployments: https://api.netq.nvidia.com/swagger/
   • On-premises deployments: https://<hostname-or-ipaddr>/swagger/
   • Cumulus in the Cloud (CITC): https://api.air.netq.nvidia.com/swagger/

   This opens the Swagger interface.

3. Select auth from the Select a definition dropdown at the top right of the window. This opens the authorization API.

1. Open a terminal window.

2. Continue to Log In instructions.

You must first obtain an access key and then use that key to authorize your access to the API.

1. Click POST/login.

2. Click Try it out.

3. Enter the username and password you used to install NetQ. For this release, the default is username admin and password admin. Do not change the access-key value.

4. Click Execute.

5. Scroll down to view the Responses. In the Server response section, in the Response body of the 200 code response, copy the access token in the top line.

6. Click Authorize.

7. Paste the access key into the Value field, and click Authorize.

8. Click Close.

To log in and obtain authorization:

1. Open a terminal window.

2. Login to obtain the access token. You will need the following information:

   • Hostname or IP address, and port (443 for Cloud deployments, 32708 for on-premises deployments) of your API gateway
   • Your login credentials that were provided as part of the NetQ installation process. For this release, the default is username admin and password admin.

   This example uses an IP address of 192.168.0.10, port of 443, and the default credentials:

   <computer-name>:~ <username>$ curl -X POST "https://api.192.168.0.10.netq.nvidia.com:443/netq/auth/v1/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"username\": \"admin\", \"password\": \"admin\", \"access_key\": \"string\"}"
   

   The output provides the access token as the first parameter.

   {"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....","customer_id":0,"expires_at":1597200346504,"id":"admin","is_cloud":true,"premises":[{"name":"OPID0","namespace":"NAN","opid":0},{"name":"ea-demo-dc-1","namespace":"ea1","opid":30000},{"name":"ea-demo-dc-2","namespace":"ea1","opid":30001},{"name":"ea-demo-dc-3","namespace":"ea1","opid":30002},{"name":"ea-demo-dc-4","namespace":"ea1","opid":30003},{"name":"ea-demo-dc-5","namespace":"ea1","opid":30004},{"name":"ea-demo-dc-6","namespace":"ea1","opid":30005},{"name":"ea-demo-dc-7","namespace":"ea1","opid":80006},{"name":"Cumulus Data Center","namespace":"NAN","opid":1568962206}],"reset_password":false,"terms_of_use_accepted":true}
   

3. Copy the access token to a text file for use in making API data requests.

API requests are easy to execute in the Swagger UI. Just select the endpoint of interest and try it out.

1. Select the endpoint from the definition dropdown at the top right of the application.

   This example shows the BGP endpoint selected:

2. Select the endpoint object.

   This example shows the results of selecting the GET bgp object:

3. Click Try it out.

4. Enter values for the required parameters.

5. Click Execute.

In a terminal window, use bash plus curl to execute requests. Each request contains an API method (GET, POST, etc.), the address and API endpoint object to query, a variety of headers, and sometimes a body. For example, in the log in step above:

• API method = POST
• Address and API object = “https://<netq.domain>:443/netq/auth/v1/login”
• Headers = -H “accept: application/json” and -H “Content-Type: application/json”
• Body = -d “{ "username": "admin", "password": "admin", "access_key": "string"}”

1. Open the check endpoint.

2. Open the check object.

3. Click Try it out.

4. Enter values for time, duration, by, and proto parameters.

   In this example, time=1597256560, duration=24, by=scheduled, and proto=bgp.

5. Click Execute, then scroll down to see the results under Server response.

Run the following curl command, entering values for the various parameters. In this example, time=1597256560, duration=24 (hours), by=scheduled, and proto=bgp.

curl -X GET "<https://<netq.domain>:<port>/netq/telemetry/v1/object/check?time=1597256560&duration=24&by=scheduled&proto=bgp" -H "accept: application/json" -H  "Authorization: <auth-token> " | python -m json.tool

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 22869  100 22869    0     0  34235      0 --:--:-- --:--:-- --:--:-- 34183
{
    "count": 24,
    "data": [
        {
            "additional_summary": {
                "failed_sessions": 0,
                "total_sessions": 0
            },
            "failed_node_set": [],
            "jobid": "c5c046d1-3cc5-4c8b-b4e8-cf2bbfb050e6",
            "res_timestamp": 1597254743280,
            "rotten_node_set": [],
            "summary": {
                "checkedNodeCount": 0,
                "failedNodeCount": 0,
                "failedSessionCount": 0,
                "rottenNodeCount": 0,
                "totalNodeCount": 0,
                "totalSessionCount": 0,
                "warningNodeCount": 0
            },
...

This example uses the server01 switch.

1. Open the EVPN endpoint.

2. Open the hostname object.

3. Click Try it out.

4. Enter a value for hostname, and optional values for eq_timestamp, count, and offset parameters.

   In this example, time=1597256560, duration=24, by=scheduled, and proto=bgp.

5. Click Execute, then scroll down to see the results under Server response.

This example uses the server01 switch in an on-premises network deployment.

curl -X GET "https://<netq.domain>:32708/netq/telemetry/v1/object/evpn/hostname/spine01" -H "accept: application/json" -H "Authorization: <auth-token>" | python -m json.tool

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100     2    0     2    0     0      3      0 --:--:-- --:--:-- --:--:--     3
[]


<!-- old output -->

[
    {
    "import_rt": "[\"197:42\"]",
    "vni": 42,
    "rd": "27.0.0.22:2",
    "hostname": "server01",
    "timestamp": 1556037403853,
    "adv_all_vni": true,
    "export_rt": "[\"197:42\"]",
    "db_state": "Update",
    "in_kernel": true,
    "adv_gw_ip": "Disabled",
    "origin_ip": "27.0.0.22",
    "opid": 0,
    "is_l3": false
    },
    {
    "import_rt": "[\"197:37\"]",
    "vni": 37,
    "rd": "27.0.0.22:8",
    "hostname": "server01",
    "timestamp": 1556037403811,
    "adv_all_vni": true,
    "export_rt": "[\"197:37\"]",
    "db_state": "Update",
    "in_kernel": true,
    "adv_gw_ip": "Disabled",
    "origin_ip": "27.0.0.22",
    "opid": 0,
    "is_l3": false
    },
    {
    "import_rt": "[\"197:4001\"]",
    "vni": 4001,
    "rd": "6.0.0.194:5",
    "hostname": "server01",
    "timestamp": 1556036360169,
    "adv_all_vni": true,
    "export_rt": "[\"197:4001\"]",
    "db_state": "Refresh",
    "in_kernel": true,
    "adv_gw_ip": "Disabled",
    "origin_ip": "27.0.0.22",
    "opid": 0,
    "is_l3": true
    },
...