HomeGuidesAPI Reference
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In

Tips and Tricks with AOS-CX REST

Optional "selector" parameter

When making GET calls, users can specify an optional parameter, "selector." The selector allows filtering of the returned response body to contain only specific key-value pairs. The selector options are:

Option

Explanation

configuration

Retrieves key-value pair attributes associated with configuring the Resource

status

Retrieves key-value pair attributes associated with health status of the device

statistics

Retrieves key-value pair attributes associated with device statistics

writable

Retrieves key-value pair attributes associated with attributes that are mutable

Optional "depth" parameter

The "depth" parameter allows expanding nested URIs to show the key-value pairs of those resources in JSON responses.
For a given depth 'n', if the response contained URIs, then a depth of 'n+1' would receive a response with the full bodies of the resources for the previous URIs. Consequently, if the response for 'n+1' contained URIs, then a depth of 'n+2' would expand the bodies of the resources within 'n+1' responses.

Depth is a non-negative integer value, and in REST API v10.04 the default value is 1.
For example, here is a GET call for VLANS with v10.04 with "depth" set to 1:

774774

v10.04 GET VLANs with Depth = 1

Comparatively, below is the same call with "depth" set to 2. Note that the VLAN 1 is expanded to show the results as if a GET was pointing to the URI of VLAN 1. After VLAN 1, the response would continue to show the expanded info for VLANs 255, 2020, etc.

775775

v10.04 GET VLANs with Depth = 2

❗️

In REST API v10.04, the default depth value is 1. In the v1 API, it is 0.

Using GET before PUT

When using the REST API for workflows, the PUT method is used to update information in a resource. However, if an attribute in the JSON is not included in the PUT request body, it quite possibly may be changed to the default setting.

In order to easily create the PUT body without needing to manually include each attribute, first perform a GET on the URI and save the response, and then use that data for the PUT. It is especially useful to execute the GET with the selector as 'writable', as that will return only the key-value pairs whose values can be changed.

POST/PUT operations supported in "read-only" mode

Operation

URI

Methods (PUT / POST)

Configuration management

/rest/v10.04/fullconfigs/

PUT

Firmware uploading

/rest/v10.04/firmware/

POST

Logging into an API session

/rest/v10.04/login/

POST

Logging out of an API session

/rest/v10.04/logout/

POST

Managing NAE scripts

/rest/v10.04/system/nae_scripts/

POST and PUT

API Sessions

As of firmware version 10.05, the maximum number of concurrent HTTPS sessions per user per switch is six. There is an upper limit of 48 total sessions per switch. It is best practice to log out of an HTTPS session when you are finished using it.

HTTPS sessions will automatically time out after 20 minutes of inactivity.
HTTPS sessions also have a hard time limit of eight hours, regardless of whether the session is active.

To close all current HTTPS sessions, run the following command in the enable (#) context:

8320# https-server session close all

📘

Prior to firmware version v10.05, the maximum number of concurrent HTTPS sessions per user per switch is three.


What’s Next