ArubaOS-CX REST API Reference basics

The ArubaOS-CX REST API Reference is a web interface based on Swagger 2.0. The ArubaOS-CX REST API Reference does the following:

  • Documents the switch REST API resources, methods, models, and responses.

  • Enables you to interact with the switch to view or change the configuration.

For more information about Swagger, see https://swagger.io/.

ArubaOS-CX REST API Reference home page

The following is an example of a portion of the ArubaOS-CX REST API Reference home page for a switch running ArubaOS-CX software:

At the bottom of the page, the ArubaOS-CX REST API Reference shows base URL and version information. For example:

[ BASE URL: /rest/v1, API VERSION: 1.0.0 ]
  • The switch resource URIs are organized in groups. The group names are listed in alphabetical order on the ArubaOS-CX REST 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.

    You can also use the Show/Hide, List Operations, and Expand Operations controls to expand or collapse all the members of the group.

  • The following example shows the list of the methods and resource URIs in the Subsystem group:

    This view is the same view that is shown when you click the List Operations control of the Subsystem group.

    • 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 {id 1}, 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 shows part of the information displayed when /system/subsystems is 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.

    • Required parameters are shown in bold.

      For example, the POST method of the login resource requires a user name and password:

      Path parameters such as {id} are listed as required parameters:

    • The Submit button sends the request.

      CAUTION:

      Although the ArubaOS-CX REST API Reference interacts directly with the REST API, the ArubaOS-CX REST API Reference is not intended as a management or configuration interface. Use caution when using the Submit button 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 press Shift, and then click the last attribute in the range you want to select.

    • To select attributes that are not adjacent in the list, press Ctrl, then click each attribute you want to select.

  • The JSON model for the resource is described in Model and shown with example values in Example Values for each method. The following example shows the JSON model and example values for PUT method of the /system/subsystems/{id1}/{id2} resource:

  • After a request is submitted, the ArubaOS-CX REST 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

    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.