Using The Apstra API Docs

API Example Requests

In this section of the lab, we will perform different GET requests via the Swagger UI to pull information from Apstra. Remember from our previous labs that GET requests are safe to perform as they do not make any changes to the API, they simply retrieve information.

Basic GET Requests

For these requests to work you must have generated an API token and added it to the Swagger UI. Please refer to the previous section to generate an API token.

Get Apstra Version

This simple GET request will tell you which version of Apstra you are running.

Step 1 scroll through the Swagger UI documentation until you find version and then expand this section.
Step 2 then expand the endpoint GET /api/version
Step 3 highlights the data model we expect to be returned from performing this API call
Step 4 to perform the call, click on Try it out

api swagger get version 3

Step 1 click Execute to send the API request

api swagger get version 2

Step 1 highlights the API return for the call you just made to the /api/version endpoint.

api swagger get version 1

Stop, Have A Go

What does your instance of Apstra return? Using the steps just shown try this for yourself.

In our example here, you can see that the Apstra version we are running is 4.1.2.

Get all Apstra IP Resource Pools

This GET request will show you all the IP resource pools configured in Apstra. For the context of making API calls the IP resource pools, are just that, a range of IP addresses that are used when deploying a data center.

If you’d like to understand more about resource pools here is a link to the docs - https://www.juniper.net/documentation/us/en/software/apstra4.1/apstra-user-guide/topics/topic-map/ip-pools.html

This request will give you a list of each IP pool configured in Apstra and some information about them.

Step 1 search for resources in the filter box or scroll down
Step 2 then expand the resources section

api swagger get ip pools 4

Step 1 expand the endpoint GET /api/resources/ip-pools
Step 2 highlights the data model we expect to be returned from performing this API call
Step 3 to perform the call, click on Try it out

api swagger get ip pools 3

Step 1 click Execute to send the API request

api swagger get ip pools 2

Step 1 highlights the API return for the call you just made to the /api/resources/ip-pools endpoint.

api swagger get ip pools 1

The full output from our example can be seen below which shows multiple IP pools configured, the number of IPs in the pool and the amount already consumed by Apstra in already modeled data centers.

If you’d like evaluate the JSON response in more detail we’d recommend an online JSON parser such as http://json.parser.online.fr/

{
  "items": [
    {
      "status": "in_use",
      "subnets": [
        {
          "status": "pool_element_in_use",
          "used": "11",
          "network": "10.0.0.0/8",
          "total": "16777216",
          "used_percentage": 0.00006556510925292969
        }
      ],
      "used": "11",
      "display_name": "Private-10.0.0.0/8",
      "tags": [
        "default"
      ],
      "created_at": "2022-10-18T19:12:57.790088Z",
      "last_modified_at": "2022-10-18T19:12:57.790088Z",
      "used_percentage": 0.00006556510925292969,
      "total": "16777216",
      "id": "Private-10_0_0_0-8"
    },
    {
      "status": "in_use",
      "subnets": [
        {
          "status": "pool_element_in_use",
          "used": "12",
          "network": "192.168.0.0/16",
          "total": "65536",
          "used_percentage": 0.018310546875
        }
      ],
      "used": "12",
      "display_name": "Private-192.168.0.0/16",
      "tags": [
        "default"
      ],
      "created_at": "2022-10-18T19:12:57.789838Z",
      "last_modified_at": "2022-10-18T19:12:57.789838Z",
      "used_percentage": 0.018310546875,
      "total": "65536",
      "id": "Private-192_168_0_0-16"
    }
  ]
}

Stop, Have A Go

What does your instance of Apstra return? Using the steps just shown try this for yourself.

Apstra Onboarded Devices

This GET request will show you all the network devices onboarded into Apstra, including different information about them such as device type, NOS version and hostname.

If you have no devices onboarded into Asptra you will receive an empty reply.

Step 1 seach for systems in the filter box or scroll down
Step 2 then expand the systems section
Step 3 sthen expand the endpoint GET /api/systems.

api swagger get systems 4

Step 1 highlights the data model we expect to be returned from performing this API call
Step 2 to perform the call, click on Try it out

api swagger get systems 3

Step 1 click Execute to send the API request

api swagger get systems 2

Step 1 highlights the API return for the call you just made to the /api/system endpoint.

api swagger get systems 1

The full output from our example can be seen below which shows multiple switches already onboarded into Apstra.

If you’d like evaluate the JSON response in more detail we’d recommend an online JSON parser such as http://json.parser.online.fr/

{
  "items": [
    {
      "container_status": {
        "error": "",
        "host": "AosController",
        "name": "aos-offbox-10_29_32_13-f",
        "status": "running"
      },
      "device_key": "525400F57CE3",
      "facts": {
        "aos_hcl_model": "Juniper_vQFX",
        "aos_server": "10.29.32.3",
        "aos_version": "AOS_4.1.2_OB.91",
        "chassis_mac_ranges": "02:05:86:71:d7:00-02:05:86:72:d2:ee,02:05:86:72:d2:ef-02:05:86:72:d6:fe",
        "hw_model": "VQFX-10000",
        "hw_version": "",
        "mgmt_ifname": "em0",
        "mgmt_ipaddr": "10.29.32.13",
        "mgmt_macaddr": "52:54:00:F5:7C:E3",
        "os_arch": "x86_64",
        "os_family": "Junos",
        "os_version": "21.4R2.10",
        "os_version_info": {
          "build": "10",
          "major": "21",
          "minor": "4R2"
        },
        "serial_number": "525400F57CE3",
        "vendor": "Juniper"
      },
      "id": "525400F57CE3",
      "status": {
        "agent_start_time": "2022-10-18T23:37:44.541538Z",
        "blueprint_active": true,
        "blueprint_id": "evpn-vqfx_offbox-virtual",
        "comm_state": "on",
        "device_start_time": "2022-10-18T23:31:27.000000Z",
        "domain_name": "",
        "error_message": "",
        "fqdn": "leaf1",
        "hostname": "leaf1",
        "is_acknowledged": true,
        "operation_mode": "full_control",
        "pool_id": "default_pool",
        "state": "IS-ACTIVE"
      },
      "user_config": {
        "admin_state": "normal",
        "aos_hcl_model": "Juniper_vQFX",
        "location": "leaf1"
      }
    },
    {
      "container_status": {
        "error": "",
        "host": "AosController",
        "name": "aos-offbox-10_29_32_11-f",
        "status": "running"
      },
      "device_key": "5254000C8A38",
      "facts": {
        "aos_hcl_model": "Juniper_vQFX",
        "aos_server": "10.29.32.3",
        "aos_version": "AOS_4.1.2_OB.91",
        "chassis_mac_ranges": "02:05:86:71:1a:00-02:05:86:72:15:ee,02:05:86:72:15:ef-02:05:86:72:19:fe",
        "hw_model": "VQFX-10000",
        "hw_version": "",
        "mgmt_ifname": "em0",
        "mgmt_ipaddr": "10.29.32.11",
        "mgmt_macaddr": "52:54:00:0C:8A:38",
        "os_arch": "x86_64",
        "os_family": "Junos",
        "os_version": "21.4R2.10",
        "os_version_info": {
          "build": "10",
          "major": "21",
          "minor": "4R2"
        },
        "serial_number": "5254000C8A38",
        "vendor": "Juniper"
      },
      "id": "5254000C8A38",
      "status": {
        "agent_start_time": "2022-10-18T23:37:41.071568Z",
        "blueprint_active": true,
        "blueprint_id": "evpn-vqfx_offbox-virtual",
        "comm_state": "on",
        "device_start_time": "2022-10-18T23:30:19.000000Z",
        "domain_name": "",
        "error_message": "",
        "fqdn": "spine1",
        "hostname": "spine1",
        "is_acknowledged": true,
        "operation_mode": "full_control",
        "pool_id": "default_pool",
        "state": "IS-ACTIVE"
      },
      "user_config": {
        "admin_state": "normal",
        "aos_hcl_model": "Juniper_vQFX",
        "location": "spine1"
      }
    }
  ]
}

Stop, Have A Go

What does your instance of Apstra return? Using the steps just shown try this for yourself.

This section of the lab guide showed you how to do some simple GET requests via the API. These were some simple examples and depending on the data you need from Apstra, you may have to chain multiple API requests together, taking the output of one request and feeding it to the next.