HomeGuidesAPI Reference
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In
Guides

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:

OptionExplanation
configurationRetrieves key-value pair attributes associated with configuring the Resource
statusRetrieves key-value pair attributes associated with health status of the device
statisticsRetrieves key-value pair attributes associated with device statistics
writableRetrieves 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 from REST API v10.04 onwards, the default value is 1.
For example, here is a GET call for VLANS with v10.13 with "depth" set to 1:

curl -X GET "https://<switch-ip>/rest/v10.13/system/vlans?depth=1" -H  "accept: application/json" -H  "x-csrf-token: <csrf-token>"
{
  "1": "/rest/v10.13/system/vlans/1",
  "20": "/rest/v10.13/system/vlans/20",
  "100": "/rest/v10.13/system/vlans/100",
  "255": "/rest/v10.13/system/vlans/255",
  "2020": "/rest/v10.13/system/vlans/2020"
}

Comparatively, below is the same call with "depth" set to 2. Note that each of the VLANs now has expanded information in the API response.

curl -X GET "https://<switch-ip>/rest/v10.13/system/vlans?depth=2" -H  "accept: application/json" -H  "x-csrf-token: <csrf-token>"
{
  "1": {
    "aclmac_in_applied": null,
    "aclmac_in_cfg": null,
    "aclmac_in_cfg_version": null,
    "aclmac_in_data_plane_states": {},
    "aclmac_in_statistics": {},
    "aclmac_in_status": {},
    "aclv4_in_applied": null,
    "aclv4_in_cfg": null,
    "aclv4_in_cfg_version": null,
    "aclv4_in_data_plane_states": {},
    "aclv4_in_statistics": {},
    "aclv4_in_status": {},
    "aclv4_out_applied": null,
    "aclv4_out_cfg": null,
    "aclv4_out_cfg_version": null,
    "aclv4_out_data_plane_states": {},
    "aclv4_out_statistics": {},
    "aclv4_out_status": {},
    "aclv6_in_applied": null,
    "aclv6_in_cfg": null,
    "aclv6_in_cfg_version": null,
    "aclv6_in_data_plane_states": {},
    "aclv6_in_statistics": {},
    "aclv6_in_status": {},
    "aclv6_out_applied": null,
    "aclv6_out_cfg": null,
    "aclv6_out_cfg_version": null,
    "aclv6_out_data_plane_states": {},
    "aclv6_out_statistics": {},
    "aclv6_out_status": {},
    "admin": "up",
    "clear_ip_bindings": {},
    "delete_macs_rejected": {},
    "delete_macs_requested": {},
    "description": null,
    "flood_enabled_subsystems": {},
    "id": 1,
    "internal_usage": {},
    "macs": "/rest/v10.13/system/vlans/1/macs",
    "macs_invalid": null,
    "mgmd_counters": {},
    "mgmd_drop_unknown_status": {},
    "mgmd_dynamic_group_count": {},
    "mgmd_enable": {},
    "mgmd_enable_status": {},
    "mgmd_igmp_block_ports": {},
    "mgmd_igmp_fastleave_ports": {},
    "mgmd_igmp_forcedfastleave_ports": {},
    "mgmd_igmp_forward_ports": {},
    "mgmd_igmp_router_port_time_expiry": {},
    "mgmd_igmp_static_groups": [],
    "mgmd_igmp_version": null,
    "mgmd_mld_block_ports": {},
    "mgmd_mld_fastleave_ports": {},
    "mgmd_mld_forcedfastleave_ports": {},
    "mgmd_mld_forward_ports": {},
    "mgmd_mld_router_port_time_expiry": {},
    "mgmd_mld_static_groups": [],
    "mgmd_mld_version": null,
    "mgmd_oper_version": {},
    "mgmd_querier_ip": {},
    "mgmd_querier_port": {},
    "mgmd_querier_timer_info": {},
    "mgmd_snooping_acl": {},
    "mgmd_vgs": "/rest/v10.13/system/vlans/1/mgmd_vgs",
    "name": "DEFAULT_VLAN_1",
    "oper_state": "down",
    "oper_state_reason": "no_member_port",
    "policy_in_applied": null,
    "policy_in_cfg": null,
    "policy_in_cfg_version": null,
    "policy_in_conform_rate": {},
    "policy_in_data_plane_states": {},
    "policy_in_statistics": {},
    "policy_in_status": {},
    "replication_group": null,
    "static_macs": "/rest/v10.13/system/vlans/1/static_macs",
    "type": "default",
    "voice": false,
    "vsx_sync": []
  },
  "20": {
    "aclmac_in_applied": null,
    "aclmac_in_cfg": null,
    "aclmac_in_cfg_version": null,
    "aclmac_in_data_plane_states": {},
    "aclmac_in_statistics": {},
    "aclmac_in_status": {},
    "aclv4_in_applied": null,
    "aclv4_in_cfg": null,
    "aclv4_in_cfg_version": null,
    "aclv4_in_data_plane_states": {},
    "aclv4_in_statistics": {},
    "aclv4_in_status": {},
    "aclv4_out_applied": null,
    "aclv4_out_cfg": null,
    "aclv4_out_cfg_version": null,
    "aclv4_out_data_plane_states": {},
    "aclv4_out_statistics": {},
    "aclv4_out_status": {},
    "aclv6_in_applied": null,
    "aclv6_in_cfg": null,
    "aclv6_in_cfg_version": null,
    "aclv6_in_data_plane_states": {},
    "aclv6_in_statistics": {},
    "aclv6_in_status": {},
    "aclv6_out_applied": null,
    "aclv6_out_cfg": null,
    "aclv6_out_cfg_version": null,
    "aclv6_out_data_plane_states": {},
    "aclv6_out_statistics": {},
    "aclv6_out_status": {},
    "admin": "up",
    "clear_ip_bindings": {},
    "delete_macs_rejected": {},
    "delete_macs_requested": {},
    "description": null,
    "flood_enabled_subsystems": {},
    "id": 20,
    "internal_usage": {},
    "macs": "/rest/v10.13/system/vlans/20/macs",
    "macs_invalid": null,
    "mgmd_counters": {},
    "mgmd_drop_unknown_status": {},
    "mgmd_dynamic_group_count": {},
    "mgmd_enable": {},
    "mgmd_enable_status": {},
    "mgmd_igmp_block_ports": {},
    "mgmd_igmp_fastleave_ports": {},
    "mgmd_igmp_forcedfastleave_ports": {},
    "mgmd_igmp_forward_ports": {},
    "mgmd_igmp_router_port_time_expiry": {},
    "mgmd_igmp_static_groups": [],
    "mgmd_igmp_version": null,
    "mgmd_mld_block_ports": {},
    "mgmd_mld_fastleave_ports": {},
    "mgmd_mld_forcedfastleave_ports": {},
    "mgmd_mld_forward_ports": {},
    "mgmd_mld_router_port_time_expiry": {},
    "mgmd_mld_static_groups": [],
    "mgmd_mld_version": null,
    "mgmd_oper_version": {},
    "mgmd_querier_ip": {},
    "mgmd_querier_port": {},
    "mgmd_querier_timer_info": {},
    "mgmd_snooping_acl": {},
    "mgmd_vgs": "/rest/v10.13/system/vlans/20/mgmd_vgs",
    "name": "terraform_vlan",
    "oper_state": "down",
    "oper_state_reason": "no_member_port",
    "policy_in_applied": null,
    "policy_in_cfg": null,
    "policy_in_cfg_version": null,
    "policy_in_conform_rate": {},
    "policy_in_data_plane_states": {},
    "policy_in_statistics": {},
    "policy_in_status": {},
    "replication_group": null,
    "static_macs": "/rest/v10.13/system/vlans/20/static_macs",
    "type": "static",
    "voice": false,
    "vsx_sync": []
  },
  "100": {
    "aclmac_in_applied": null,
    "aclmac_in_cfg": null,
    "aclmac_in_cfg_version": null,
    "aclmac_in_data_plane_states": {},
    "aclmac_in_statistics": {},
    "aclmac_in_status": {},
    "aclv4_in_applied": null,
    "aclv4_in_cfg": null,
    "aclv4_in_cfg_version": null,
    "aclv4_in_data_plane_states": {},
    "aclv4_in_statistics": {},
    "aclv4_in_status": {},
    "aclv4_out_applied": null,
    "aclv4_out_cfg": null,
    "aclv4_out_cfg_version": null,
    "aclv4_out_data_plane_states": {},
    "aclv4_out_statistics": {},
    "aclv4_out_status": {},
    "aclv6_in_applied": null,
    "aclv6_in_cfg": null,
    "aclv6_in_cfg_version": null,
    "aclv6_in_data_plane_states": {},
    "aclv6_in_statistics": {},
    "aclv6_in_status": {},
    "aclv6_out_applied": null,
    "aclv6_out_cfg": null,
    "aclv6_out_cfg_version": null,
    "aclv6_out_data_plane_states": {},
    "aclv6_out_statistics": {},
    "aclv6_out_status": {},
    "admin": "up",
    "clear_ip_bindings": {},
    "delete_macs_rejected": {},
    "delete_macs_requested": {},
    "description": null,
    "flood_enabled_subsystems": {},
    "id": 100,
    "internal_usage": {},
    "macs": "/rest/v10.13/system/vlans/100/macs",
    "macs_invalid": null,
    "mgmd_counters": {},
    "mgmd_drop_unknown_status": {},
    "mgmd_dynamic_group_count": {},
    "mgmd_enable": {},
    "mgmd_enable_status": {},
    "mgmd_igmp_block_ports": {},
    "mgmd_igmp_fastleave_ports": {},
    "mgmd_igmp_forcedfastleave_ports": {},
    "mgmd_igmp_forward_ports": {},
    "mgmd_igmp_router_port_time_expiry": {},
    "mgmd_igmp_static_groups": [],
    "mgmd_igmp_version": null,
    "mgmd_mld_block_ports": {},
    "mgmd_mld_fastleave_ports": {},
    "mgmd_mld_forcedfastleave_ports": {},
    "mgmd_mld_forward_ports": {},
    "mgmd_mld_router_port_time_expiry": {},
    "mgmd_mld_static_groups": [],
    "mgmd_mld_version": null,
    "mgmd_oper_version": {},
    "mgmd_querier_ip": {},
    "mgmd_querier_port": {},
    "mgmd_querier_timer_info": {},
    "mgmd_snooping_acl": {},
    "mgmd_vgs": "/rest/v10.13/system/vlans/100/mgmd_vgs",
    "name": "GO_TEST_VLAN",
    "oper_state": "down",
    "oper_state_reason": "no_member_port",
    "policy_in_applied": null,
    "policy_in_cfg": null,
    "policy_in_cfg_version": null,
    "policy_in_conform_rate": {},
    "policy_in_data_plane_states": {},
    "policy_in_statistics": {},
    "policy_in_status": {},
    "replication_group": null,
    "static_macs": "/rest/v10.13/system/vlans/100/static_macs",
    "type": "static",
    "voice": false,
    "vsx_sync": []
  },
  "255": {
    "aclmac_in_applied": null,
    "aclmac_in_cfg": null,
    "aclmac_in_cfg_version": null,
    "aclmac_in_data_plane_states": {},
    "aclmac_in_statistics": {},
    "aclmac_in_status": {},
    "aclv4_in_applied": null,
    "aclv4_in_cfg": null,
    "aclv4_in_cfg_version": null,
    "aclv4_in_data_plane_states": {},
    "aclv4_in_statistics": {},
    "aclv4_in_status": {},
    "aclv4_out_applied": null,
    "aclv4_out_cfg": null,
    "aclv4_out_cfg_version": null,
    "aclv4_out_data_plane_states": {},
    "aclv4_out_statistics": {},
    "aclv4_out_status": {},
    "aclv6_in_applied": null,
    "aclv6_in_cfg": null,
    "aclv6_in_cfg_version": null,
    "aclv6_in_data_plane_states": {},
    "aclv6_in_statistics": {},
    "aclv6_in_status": {},
    "aclv6_out_applied": null,
    "aclv6_out_cfg": null,
    "aclv6_out_cfg_version": null,
    "aclv6_out_data_plane_states": {},
    "aclv6_out_statistics": {},
    "aclv6_out_status": {},
    "admin": "up",
    "clear_ip_bindings": {},
    "delete_macs_rejected": {},
    "delete_macs_requested": {},
    "description": null,
    "flood_enabled_subsystems": {},
    "id": 255,
    "internal_usage": {},
    "macs": "/rest/v10.13/system/vlans/255/macs",
    "macs_invalid": null,
    "mgmd_counters": {},
    "mgmd_drop_unknown_status": {},
    "mgmd_dynamic_group_count": {},
    "mgmd_enable": {},
    "mgmd_enable_status": {},
    "mgmd_igmp_block_ports": {},
    "mgmd_igmp_fastleave_ports": {},
    "mgmd_igmp_forcedfastleave_ports": {},
    "mgmd_igmp_forward_ports": {},
    "mgmd_igmp_router_port_time_expiry": {},
    "mgmd_igmp_static_groups": [],
    "mgmd_igmp_version": null,
    "mgmd_mld_block_ports": {},
    "mgmd_mld_fastleave_ports": {},
    "mgmd_mld_forcedfastleave_ports": {},
    "mgmd_mld_forward_ports": {},
    "mgmd_mld_router_port_time_expiry": {},
    "mgmd_mld_static_groups": [],
    "mgmd_mld_version": null,
    "mgmd_oper_version": {},
    "mgmd_querier_ip": {},
    "mgmd_querier_port": {},
    "mgmd_querier_timer_info": {},
    "mgmd_snooping_acl": {},
    "mgmd_vgs": "/rest/v10.13/system/vlans/255/mgmd_vgs",
    "name": "VLAN255",
    "oper_state": "up",
    "oper_state_reason": "ok",
    "policy_in_applied": null,
    "policy_in_cfg": null,
    "policy_in_cfg_version": null,
    "policy_in_conform_rate": {},
    "policy_in_data_plane_states": {},
    "policy_in_statistics": {},
    "policy_in_status": {},
    "replication_group": null,
    "static_macs": "/rest/v10.13/system/vlans/255/static_macs",
    "type": "static",
    "voice": false,
    "vsx_sync": []
  },
  "2020": {
    "aclmac_in_applied": null,
    "aclmac_in_cfg": null,
    "aclmac_in_cfg_version": null,
    "aclmac_in_data_plane_states": {},
    "aclmac_in_statistics": {},
    "aclmac_in_status": {},
    "aclv4_in_applied": null,
    "aclv4_in_cfg": null,
    "aclv4_in_cfg_version": null,
    "aclv4_in_data_plane_states": {},
    "aclv4_in_statistics": {},
    "aclv4_in_status": {},
    "aclv4_out_applied": null,
    "aclv4_out_cfg": null,
    "aclv4_out_cfg_version": null,
    "aclv4_out_data_plane_states": {},
    "aclv4_out_statistics": {},
    "aclv4_out_status": {},
    "aclv6_in_applied": null,
    "aclv6_in_cfg": null,
    "aclv6_in_cfg_version": null,
    "aclv6_in_data_plane_states": {},
    "aclv6_in_statistics": {},
    "aclv6_in_status": {},
    "aclv6_out_applied": null,
    "aclv6_out_cfg": null,
    "aclv6_out_cfg_version": null,
    "aclv6_out_data_plane_states": {},
    "aclv6_out_statistics": {},
    "aclv6_out_status": {},
    "admin": "up",
    "clear_ip_bindings": {},
    "delete_macs_rejected": {},
    "delete_macs_requested": {},
    "description": null,
    "flood_enabled_subsystems": {},
    "id": 2020,
    "internal_usage": {},
    "macs": "/rest/v10.13/system/vlans/2020/macs",
    "macs_invalid": null,
    "mgmd_counters": {},
    "mgmd_drop_unknown_status": {},
    "mgmd_dynamic_group_count": {},
    "mgmd_enable": {},
    "mgmd_enable_status": {},
    "mgmd_igmp_block_ports": {},
    "mgmd_igmp_fastleave_ports": {},
    "mgmd_igmp_forcedfastleave_ports": {},
    "mgmd_igmp_forward_ports": {},
    "mgmd_igmp_router_port_time_expiry": {},
    "mgmd_igmp_static_groups": [],
    "mgmd_igmp_version": null,
    "mgmd_mld_block_ports": {},
    "mgmd_mld_fastleave_ports": {},
    "mgmd_mld_forcedfastleave_ports": {},
    "mgmd_mld_forward_ports": {},
    "mgmd_mld_router_port_time_expiry": {},
    "mgmd_mld_static_groups": [],
    "mgmd_mld_version": null,
    "mgmd_oper_version": {},
    "mgmd_querier_ip": {},
    "mgmd_querier_port": {},
    "mgmd_querier_timer_info": {},
    "mgmd_snooping_acl": {},
    "mgmd_vgs": "/rest/v10.13/system/vlans/2020/mgmd_vgs",
    "name": "VLAN2020",
    "oper_state": "up",
    "oper_state_reason": "ok",
    "policy_in_applied": null,
    "policy_in_cfg": null,
    "policy_in_cfg_version": null,
    "policy_in_conform_rate": {},
    "policy_in_data_plane_states": {},
    "policy_in_statistics": {},
    "policy_in_status": {},
    "replication_group": null,
    "static_macs": "/rest/v10.13/system/vlans/2020/static_macs",
    "type": "static",
    "voice": false,
    "vsx_sync": []
  }
}

❗️

Default Depth between API versions

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

OperationURIMethods (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