The AOS-CX API supports the standard HTTP methods that come with a RESTful interface as well as some additional features included in the CX platform. This guide outlines the different methods and the ways they can be used to enhance AOS-CX automation.

HTTP Request Methods	Description
GET	Retrieves target resource
POST	Creates a resource
PUT	Replaces a resource, resource must exist to succeed
PATCH	Updates a resource, resource must exist to succeed
DELETE	Delete a resource

GET

The GET method is a read method that gets the resource specified by the URI. Data is returned in JSON format in the response body.

GET Wildcards

With a single endpoint requiring users to specify an "ID" or a "NAME" of a value, users may want to gather multiple or ALL of a resource. Instead of users executing multiple GET requests through a resource, users can provide an asterisk * (encoded as %2A) as a wildcard and the API will return all the entries of that resource.

For example, it is a common use case to gather the LLDP neighbors of a switch using the endpoint https://switch-ip/rest/v10.15/system/interfaces/{Interface.name}/lldp_neighbors. Instead of repeating that GET request providing every Interface value, using the wildcard we get the LLDP neighbors for all interfaces on the switch:

Without Wildcard:

curl -X GET "https://10.22.5.169/rest/v10.14/system/interfaces/1%2F1%2F4/lldp_neighbors" -H  "accept: application/json" -H  "x-csrf-token: r8spmXXSiNBpaZ_xzVA=="

{
  "90:20:c2:bb:12:00,1/1/4": "/rest/v10.14/system/interfaces/1%2F1%2F4/lldp_neighbors/90%3A20%3Ac2%3Abb%3A12%3A00,1%2F1%2F4"
}

With Wildcard:

curl -X GET "https://10.22.5.169/rest/v10.14/system/interfaces/%2A/lldp_neighbors" -H  "accept: application/json" -H  "x-csrf-token: r8spmZ5F22fiNBpaZ_xzVA=="

{
  "1/1/4": {
    "90:20:c2:bb:12:00,1/1/4": "/rest/v10.14/system/interfaces/1%2F1%2F4/lldp_neighbors/90%3A20%3Ac2%3Abb%3A12%3A00,1%2F1%2F4"
  },
  "1/1/49": {
    "54:80:28:fe:6b:00,1/1/11": "/rest/v10.14/system/interfaces/1%2F1%2F49/lldp_neighbors/54%3A80%3A28%3Afe%3A6b%3A00,1%2F1%2F11"
  },
  "1/1/50": {
    "54:80:28:fe:8c:00,1/1/11": "/rest/v10.14/system/interfaces/1%2F1%2F50/lldp_neighbors/54%3A80%3A28%3Afe%3A8c%3A00,1%2F1%2F11"
  },
  "1/1/7": {
    "90:20:c2:bb:12:00,1/1/7": "/rest/v10.14/system/interfaces/1%2F1%2F7/lldp_neighbors/90%3A20%3Ac2%3Abb%3A12%3A00,1%2F1%2F7"
  }
}

👍
Best Practice
The GET method has the greatest impact on CPU and memory usage of the device due to the amount of data being processed and sent. It is recommended to take advantage of the selector parameter to retrieve pertinent data and avoid unnecessary data returned therefore improving efficiency.

Optional "selector" parameter

When making GET calls, users can specify an optional parameter, "selector." The selector parameter allows for more efficient data retrieval by filtering of the returned response body to contain only specific key-value pairs.

Syntax:

curl -X GET "https://10.22.5.169/rest/v10.14/system/interfaces/1%2F1%2F14?selector=writable" -H  "accept: application/json" -H  "x-csrf-token: ybcpEsss7BalBu3qhGZMnw=="

{
  "aaa_auth_precedence": {},
  "aaa_auth_priority": {},
  "aaa_port_access_radius_override_enable": false,
  "aclmac_in_cfg": null,
  "aclmac_in_cfg_version": null,
  "aclv4_in_cfg": null,
  "aclv4_in_cfg_version": null,
  "aclv4_out_cfg": null,
  "aclv4_out_cfg_version": null,
  "aclv4_routed_in_cfg": null,
  "aclv4_routed_in_cfg_version": null,
  "aclv4_routed_out_cfg": null,
  "aclv4_routed_out_cfg_version": null,
  "aclv6_in_cfg": null,
  "aclv6_in_cfg_version": null,
  "aclv6_routed_in_cfg": null,
  "aclv6_routed_in_cfg_version": null,
  "aclv6_routed_out_cfg": null,
  "aclv6_routed_out_cfg_version": null,
  "admin": null,
  "arp_inspection": {
    "trust": false
  },
  "arp_timeout": 1800,
  "bfd_detect_multiplier": null,
  "bfd_echo_disable": false,
  "bfd_min_rx_interval": null,
  "bfd_min_tx_interval": null,
  "bond_active_slave": null,
  "bond_mode": null,
  "cdp_disable": false,
  "cdp_pre_standard_mode": "rx_only",
  "description": null,
  "device_profile": {},
  "dhcpv4_snooping_configuration": {
    "max_bindings": 8192,
    "trusted": false
  },
  "dhcpv4_snooping_guard_policy": null,
  "dhcpv6_snooping_configuration": {
    "max_bindings": 8192,
    "trusted": false
  },
  "dhcpv6_snooping_guard_policy": null,
  "diagnostic_config": {
    "loopback_mode": "none"
  },
  "fault_monitor_profile": null,
  "headroom_cable_length": {
    "auto": false,
    "length": 350
  },
  "headroom_limit_config": {},
  "icmp_redirect_disable": false,
  "icmp_unreachable_disable": false,
  "icmp_unreachable_ratelimit": 1000,
  "igmp_router_alert_check_enable": false,
  "inter_vxlan_bridging_mode": "deny",
  "interfaces": {
    "1/1/14": "/rest/v10.14/system/interfaces/1%2F1%2F14"
  },
  "ip4_address": null,
  "ip4_address_secondary": [],
  "ip_directed_broadcast": false,
  "ip_mtu": 1500,
  "ip_neighbor_flood": false,
  "ip_tcp_mss": {},
  "ipfix_flow_monitor_in": {},
  "ipv4_source_lockdown_enable": false,
  "ipv6_address_autoconfig_enable": false,
  "ipv6_address_linklocal_enable": false,
  "ipv6_nd_dad_attempts": 1,
  "ipv6_nd_icmpv6_redirects": false,
  "ipv6_nd_mtu": 1500,
  "ipv6_nd_ns_interval": 1000,
  "ipv6_nd_prefix_default": {
    "no-advertise": false,
    "no-autoconfig": false,
    "no-onlink": false,
    "preferred_lifetime": 604800,
    "valid_lifetime": 2592000
  },
  "ipv6_nd_ra_dnssl": {},
  "ipv6_nd_ra_hoplimit": null,
  "ipv6_nd_ra_lifetime": 1800,
  "ipv6_nd_ra_managed_flag": false,
  "ipv6_nd_ra_max_interval": 600,
  "ipv6_nd_ra_min_interval": 200,
  "ipv6_nd_ra_other_config_flag": false,
  "ipv6_nd_ra_rdnss": {},
  "ipv6_nd_ra_reachable_time": 0,
  "ipv6_nd_ra_retransmit_timer": 0,
  "ipv6_nd_router_preference": "medium",
  "ipv6_nd_suppress_ra": {
    "all": true,
    "dnssl": false,
    "mtu": false,
    "rdnss": false
  },
  "ipv6_neighbor_timeout": 1800,
  "ipv6_source_lockdown_enable": false,
  "l3_counters_enable": {
    "rx": false,
    "tx": false
  },
  "lacp": null,
  "lldp_auto_flush": {
    "link_down_enable": false
  },
  "lldp_if_mgmt_config": {},
  "lldp_med_loc_civic_ca_info": {},
  "lldp_med_loc_civic_info": null,
  "lldp_med_loc_elin_info": null,
  "llfc_pool_id": 1,
  "loop_protect_action": "tx-disable",
  "loop_protect_enable": false,
  "loop_protect_stagger_count": 1,
  "loop_protect_vlan": {},
  "mac": null,
  "mac_notify_type": [],
  "mdns_sd_enable": false,
  "mdns_sd_tx_profile": null,
  "mgmd_acl": {},
  "mgmd_enable": {},
  "mgmd_igmp_static_groups": [],
  "mgmd_igmp_version": null,
  "mgmd_last_member_query_interval": {},
  "mgmd_mld_static_groups": [],
  "mgmd_mld_version": null,
  "mgmd_querier_enable": {},
  "mgmd_querier_interval": {},
  "mgmd_querier_max_response_time": {},
  "mgmd_querier_wait_time": {},
  "mgmd_robustness": {},
  "mgmd_snoop_fastlearn_enable": {},
  "mgmd_strict_version_enable": {},
  "multicast_boundary_acl_in": {},
  "multicast_boundary_acl_out": {},
  "mvrp_enable": false,
  "mvrp_forbidden_vlans": [],
  "mvrp_registration": "normal",
  "mvrp_timers": {
    "join": 20,
    "leave": 300,
    "leaveall": 1000,
    "periodic": 100
  },
  "nd_snooping_configuration": {
    "trusted": false
  },
  "options": {
    "vxlan_dest_udp_port": "4789"
  },
  "ospf_auth_keychain": null,
  "ospf_auth_md5_keys": {},
  "ospf_auth_sha_keys": {},
  "ospf_auth_text_key": null,
  "ospf_auth_type": "null",
  "ospf_bfd": "default",
  "ospf_if_out_cost": null,
  "ospf_if_shutdown": false,
  "ospf_if_type": null,
  "ospf_intervals": {
    "dead_interval": 40,
    "hello_interval": 10,
    "retransmit_interval": 5,
    "transmit_delay": 1
  },
  "ospf_priority": 1,
  "ospfv3_bfd": "default",
  "ospfv3_dead_interval": 40,
  "ospfv3_hello_interval": 10,
  "ospfv3_if_cost": null,
  "ospfv3_if_priority": 1,
  "ospfv3_if_shutdown": false,
  "ospfv3_if_type": null,
  "ospfv3_ipsec_ah": {
    "ah_null": false
  },
  "ospfv3_ipsec_esp": {
    "esp_null": false
  },
  "ospfv3_retransmit_interval": 5,
  "ospfv3_transmit_delay": 1,
  "other_config": {
    "lldp_dcbx_disable": false,
    "lldp_dot3_macphy_disable": false,
    "lldp_dot3_mfs_disable": false,
    "lldp_med_capability_disable": false,
    "lldp_med_network_policy_disable": false,
    "lldp_med_topology_notification_disable": false,
    "lldp_trap_enable": true
  },
  "persona": {},
  "pfc_priorities_config": {},
  "pim_bfd": {},
  "pim_bsr_boundary": {
    "ipv4": false,
    "ipv6": false
  },
  "pim_datapath_auto_include": {
    "ipv4": false,
    "ipv6": false
  },
  "pim_dense_graft_retry_interval": {},
  "pim_dense_max_graft_retries": {},
  "pim_dense_ttl_threshold": {},
  "pim_dr_priority": {},
  "pim_hello_interval": {},
  "pim_lan_prune_delay_disable": {},
  "pim_mode": {
    "ipv4": "disabled",
    "ipv6": "disabled"
  },
  "pim_override_interval": {},
  "pim_propagation_delay": {},
  "pim_source_address": {},
  "pim_trig_hello_interval": {},
  "pim_vsx_virtual_neighbor": {
    "ipv4": false,
    "ipv6": false
  },
  "policy_in_cfg": null,
  "policy_in_cfg_version": null,
  "policy_routed_in_cfg": null,
  "policy_routed_in_cfg_version": null,
  "port_access_allow_bpdu": [],
  "port_access_allow_flood_traffic": false,
  "port_access_auth_mode": "client-mode",
  "port_access_auth_role": null,
  "port_access_clients_limit": 1,
  "port_access_concurrent_onboarding": false,
  "port_access_critical_auth_role": null,
  "port_access_disable_cdp_auth": false,
  "port_access_disable_lldp_auth": false,
  "port_access_enable_client_auto_logoff": {
    "final_authentication_failure_enable": false
  },
  "port_access_fallback_role": null,
  "port_access_lldp_authentication_mac": "chassis-mac",
  "port_access_onboarding_precedence": {},
  "port_access_pre_auth_role": null,
  "port_access_reject_role": null,
  "port_access_security_violation": {
    "action": "notify",
    "recovery_timer": 10,
    "shutdown_recovery_enable": false
  },
  "port_security": {
    "client_limit": 1,
    "enable": false,
    "sticky_mac_learning_enable": false
  },
  "port_security_static_client_mac_addr": [],
  "port_security_static_sticky_client_mac_addr": {},
  "process_grat_arp": true,
  "ptp_1588v2_profile_timers": {
    "announce_receipt_timeout": 3,
    "log_announce_interval": 1,
    "log_min_delay_req_interval": 0,
    "log_sync_interval": 0
  },
  "ptp_aes67_profile_timers": {
    "announce_receipt_timeout": 3,
    "log_announce_interval": 1,
    "log_min_delay_req_interval": 0,
    "log_sync_interval": -3
  },
  "ptp_aes_r16_profile_timers": {
    "announce_receipt_timeout": 3,
    "log_announce_interval": 1,
    "log_min_delay_req_interval": 0
  },
  "ptp_clock_source_only": false,
  "ptp_dot1as_profile_timers": {
    "announce_receipt_timeout": 3,
    "log_announce_interval": 0,
    "log_sync_interval": -3,
    "sync_receipt_timeout": 3
  },
  "ptp_enable": false,
  "ptp_lag_role": null,
  "ptp_neighbor_prop_delay_threshold": 800,
  "ptp_peer_unicast_ip_address": [],
  "ptp_smpte_profile_timers": {
    "announce_receipt_timeout": 3,
    "log_announce_interval": -2,
    "log_min_delay_req_interval": -3,
    "log_sync_interval": -3
  },
  "ptp_vlan": null,
  "pvlan_port_type": null,
  "q_profile": null,
  "qinq_admin_port_type": "auto",
  "qinq_mapped_access_vlan": {},
  "qos": null,
  "qos_config": {},
  "rate_interval": 300,
  "rate_limits": {
    "broadcast_units": "kbps",
    "egress_shape_rate_units": "kbps",
    "multicast_units": "kbps",
    "unknown-unicast_units": "kbps"
  },
  "rdisc_irdp_broadcast": false,
  "rdisc_irdp_enable": false,
  "rdisc_irdp_preference": 0,
  "rdisc_irdp_timers": {
    "irdp_hold_time": 1800,
    "irdp_maxadv_interval": 600,
    "irdp_minadv_interval": 450
  },
  "routing": true,
  "selftest_disable": false,
  "ssm_map_acl": {},
  "stp_config": {
    "admin_edge_port_enable": false,
    "bpdu_filter_enable": false,
    "bpdu_guard_enable": false,
    "bpdus_rx_disable": false,
    "bpdus_tx_disable": false,
    "link_type": "auto",
    "loop_guard_enable": false,
    "port_priority": 128,
    "protocol_migration_disable": false,
    "restricted_port_role_disable": false,
    "restricted_port_tcn_disable": false,
    "root_guard_enable": false,
    "rpvst_filter_enable": false,
    "rpvst_guard_enable": false
  },
  "subintf_vlan": null,
  "threshold_profile": null,
  "traffic_insight_flow_collector_interface": false,
  "transport_vrf": null,
  "udld_arubaos_compatibility_mode": "forward_then_verify",
  "udld_compatibility": "aruba_os",
  "udld_enable": false,
  "udld_interval": 7000,
  "udld_retries": 4,
  "udld_rfc5171_compatibility_mode": "normal",
  "unknown_unicast_forwarding_block": false,
  "unnumbered": {},
  "urpf_check": "disable",
  "user_config": {
    "error_control": "auto",
    "interpacket_gap": "standard",
    "leader_follower": "preferred-leader",
    "link_clock_tolerance": "wide",
    "link_state_snmp_if_mib_trap": true,
    "link_state_snmp_trap": true,
    "pause_override": false,
    "pause_watchdog": false,
    "speed_override": false,
    "split_count": "4"
  },
  "virtual_gw_l3_src_mac_enable": false,
  "vlan_mode": null,
  "vlan_tag": null,
  "vlan_translations": {},
  "vlan_trunks": {},
  "vlans_per_protocol": {},
  "vrf": null,
  "vrrp_dual_active_forwarding": false,
  "vsx_active_forwarding_enable": false,
  "vsx_linkup_delay_timer_disable": false,
  "vsx_shutdown_on_split": false,
  "vsx_sync": [],
  "vsx_virtual_gw_mac_v4": null,
  "vsx_virtual_gw_mac_v6": null,
  "vsx_virtual_ip4": [],
  "vsx_virtual_ip6": [],
  "vxlan_counters": {
    "aggregate": false
  },
  "xoff_limit_config": {},
  "xon_delta_config": {}
}

The selector options are:

Option	Explanation
configuration	Retrieves read/write key-value pair attributes associated with configuring the Resource
status	Retrieves non-statistic read-only key-value pair attributes associated with health status of the device
statistics	Retrieves read-only key-value pair attributes associated with device statistics
writable	Retrieves write key-value pair attributes associated with attributes that are mutable and can only be modified in PUT and PATCH operations

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 and later, the default depth value is 1. In v1 API, it is 0.

POST

The POST method is used to send data to create/update a resource specified by the URI. The resource you are creating is sent in JSON format in the request body. When attempting to replicate CLI based configurations on the switch, most resources have a hierarchical relationship. This means that most resources have a parent/child relationship and multiple API calls may be required to achieve an equivalent CLI command.

PUT

The PUT method replaces the existing resource with the data provided in the request body. When executing a PUT request, the system will expect a full body/payload and will replace each value with what was provided. To update only specific attributes use the PATCH method.

It it recommended to use the PATCH method whenever possible to update resources, If PUT is to be used, the recommendation is to first use the GET method with selector=writable to obtain the writable (mutable) configuration attributes, then change the values of the attributes to match the desired configuration.

🚧
NOTE
Some attributes are immutable and therefore they can only be set at the time of creation. If a non-writable and/or immutable attribute is part of the JSON body, the request will return a 400 Bad Request response code.

PATCH

The PATCH method is used to update values in an already existing resource and allows users to provide only the desired values in the request body and leaves all other values in the resource untouched.

Since PATCH only uses the desired values in the request body, there is no need to fetch the current resource in order to send a new request (like the PUT method), which simplifies the automation and reduces bandwidth usage. PATCH also doesn't support deleting elements from a resource, meaning that it is only possible to add/update new values. For cases in deleting content from a resource, a PUT request is needed.

DELETE

The DELETE method is used to delete a resource from the switch. Some resources do not support the DELETE method so refer to the AOS-CX API Reference when making request.

HTTP Response Codes

The REST API has three different categories of response codes:

2xx: Indicates that the request was accepted successfully.
4xx: Returns the client-side error response with the error message.
5xx: Returns the server-side error response with the error message.

The following table lists the response codes that can be found when using the REST API:

Response Code	Status	Description
200	OK	Returned from GET and POST operations (e.g Login or Logout) when the request is successfully completed.
201	Created	Returned from POST operations when a new resource was successfully created.
204	No Content	Returned from a PUT, PATCH, or DELETE operation when the request was successfully processed and there is no content to return.
400	Bad request	A problem with the request body, such as invalid syntax, incorrectly formatted JSON, or data violating a database constraint.
401	Unauthorized	No active session for this client (the login API has not been called) or too many sessions already created from this client.
403	Forbidden	The client session is valid, but does not have permissions to access the requested resource.
404	Not found	The resource does not exist, or the URI is incorrect for the desired resource.
405	Method Not Allowed	The method is not valid for that specific resource, returned for PATCH, PUT, DELETE methods.
429	Too Many Requests	When the endpoint's rate limit is reached. More information about the rate limit here.
500	Internal server error	An unexpected error has occurred in processing the request. Check the logs on the device for details.
501	Not Implemented	The server does not support the functionality required to handle the request.
503	Service unavailable	The device is not ready to handle the request.

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

API Methods & Best Practices

GET

GET Wildcards

👍
Best Practice

Optional "selector" parameter

Optional "depth" parameter

❗️
Default Depth between API versions

POST

PUT

🚧
NOTE

PATCH

DELETE

HTTP Response Codes

API Sessions

GET

GET Wildcards

👍Best Practice

Optional "selector" parameter

Optional "depth" parameter

❗️Default Depth between API versions

POST

PUT

🚧NOTE

PATCH

DELETE

HTTP Response Codes

API Sessions

👍
Best Practice

❗️
Default Depth between API versions

🚧
NOTE