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 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
| 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.
Updated 3 months ago
What’s Next