AOS-CXREST API Reference basics
This section provides information about the different components of theAOS-CXREST API user interface.
AOS-CX REST API Reference home page
The following is an example of a portion of theAOS-CXREST API Reference home page for a switch runningAOS-CXsoftware:
- The link at the top of the page displays the JSON representation of the RESTful interface.
- TheServersdrop-down lists the base URL to access the REST API.
The switch resource URIs are organized in groups. The group names are listed in alphabetical order on theAOS-CXREST API Reference home page.
The group name does not always match the resource collection name. Use the group names as a navigation aid only.
Group names that are in gray have the URI entries—also called endpoints—collapsed. When you hover over the group name, it turns black. Click the group name to expand it and show the list of methods and URIs in the group.
The following example shows the list of the methods and URIs in theSubsystemgroup:
The methods that are shown might depend on the REST API access mode. Some methods might not be displayed if the REST API access mode is
read-only.Methods and resources might be displayed that you do not have the authorization to access. For example, users with operator rights are not authorized to make PUT or POST requests to most resources. If you submit a request for which you are not authorized, the switch returns the following error:
HTTP error 403 "Forbidden"The resource collection name is
subsystems(not Subsystem).Items in braces, such as
{type}and{name}, are path parameters. If you submit a request to a resource URI that includes a path parameter, you are required to supply a value for the parameter.
To show more information about an item on the list, click the URI path. The following example shows a part of the information displayed when GET on
/system/subsystemsis selected:
You can use the browser scroll bar to navigate to information about the implementation of this method and resource, including the required and optional parameters. You must clickTry it outto edit the parameters.
The required parameters are shown with* required.
例如,the POST method of the login resource requires a user name and password:
Path parameters, such as
{id}根据需要,列出参数:
TheExecutebutton sends the request. ClickCancelto exit the edit mode without sending the request.
CAUTION:Although theAOS-CXREST API Reference interacts directly with the REST API, theAOS-CXREST API Reference is not intended as a management or configuration interface. Use caution when using theExecutebutton for POST or PUT methods because this action can result in changes to your current environment.
In GET requests, there can be multiple attributes and parameters you can use to filter results.
For example:
You can select multiple attributes:
To select a range of attributes, click the first attribute, then pressShift, and then click the last attribute in the range you want to select.
To select attributes that are not adjacent in the list, pressCtrl, then click each attribute you want to select.
The JSON model for the resource is described inModeland shown with example values inExample Valuesfor each method. The following example shows the JSON model and example values for PUT method of the
/system/subsystems/{type}/{name}resource:
After a request is submitted, theAOS-CXREST API Reference shows additional information, including the following:
The curl command equivalent of the submitted request
The submitted request URL, including the specified parameters and values.
The response body returned by the switch
The response code returned by the switch
The response headers returned by the switch
The curl command and request URLs are displayed using percent encoding for certain characters in the query string portion of the URL:
Character Percent-encoded equivalent ,(comma)%2C :(colon)%3A /(forward slash)%2F When you enter curl commands or submit requests through other means, percent encoding is permitted but not required in the query string of the URI.
