Getting Started with REST API

Interface

The interface used to access the configuration elements on Mobility Conductor is HTTPS. HTTPS is used because it provides transport layer security, and hence the passwords and other secret information can be sent without worrying about anyone interfering. The same interface is used for all Managed Devices irrespective of a hardware-based or a Virtual Machine (VM) based platform. It works for Mobility Conductors (MCR), Mobility Controller/Managed Device (MD) (managed by MCR) and Standalone Controllers.

By default, the REST API operates on port 4343 on the MCR and MD. API endpoints and API objects are used interchangeably throughout this guide.

Type of API Endpoints

There are different type of API endpoints available to deal with different type of operations. These include APIs for Authentication - Login & Logout, Device Configuration, Device Monitoring & Status Checks, etc. These different types are listed below.

Login

• Login is a special endpoint that is required to access any configuration element using GET or POST method with any API endpoint
• It is used for authenticating a user to access APIs on the MCR/MD/Standalone.
• Access is granted using UIDARUBA token which is generated using administrator username and password and given as a response for the API call made to the Login endpoint
• More details on how the use this endpoint are given in the next section

📘

Note

Once a user is successfully authenticated and has a valid UIDARUBA token, it is a good practice to securely store and reuse the same token for subsequent API calls till the token expires. This will not only avoid creating multiple sessions on the system, but it will also avoid doing a login for every API call.

 

Logout

• To logout from an existing session, Logout API endpoint is used
• Once logged out, GET or POST requests cannot be run until login endpoint is called again to obtain a new UIDARUBA token
• More details on how the use this endpoint are given in the next section

📘

Note

HTTPS is the interface that is used to access any AOS8 API endpoints.

📘

Note

AOS8 APIs can be used both on Mobility Conductor as well as Standalone devices.

 

Configuration APIs

• These APIs are used to configure the system using the POST method or fetch the configured data from the system data-stores using the GET method
• Only GET and POST HTTP methods are supported on the controllers

🚧

Note

Since configuration APIs interact with the data stores, only configuration commands will work using APIs, action commands which do not configure the system are not supported.

 

Monitoring APIs

Apart from the various endpoints available for GET, monitoring can also be achieved using the CLI "show commands" over APIs. All show commands available on the CLI can be called over API using the showcommand endpoint.

Show Command API

• It mimics the CLI show commands over API
• Response to this API call is a structured JSON response for a show command, which can be used further by external applications
• Only GET method is supported for this type of API

🚧

Note

Most showcommand API give a structured JSON response.

 

Write Memory

Write Memory API is used to deploy the pending changes made to the Mobility Conductor through POST API calls. Once a user has made a successful POST request, there will be configuration changes on the system, which will be in pending state for the given configuration path. Write memory API is used to apply these pending changes.

This is helpful when an admin needs to verify the changes once before they are actually applied to the system.

🚧

Note

write_memory endpoint request doesn't have data/payload and has to be called for every config_path which has pending changes.

 

Response Codes

While dealing with the REST API on AOS8, you will encounter 'HTTP Response Codes' as well as AOS8 controller 'Status Codes'.

The possible HTTP Response Codes that the API on AOS8 controller might return are listed in the below table:

The possible Status Codes are listed in the below table:

❗️

Reading the Response Code

In some cases, you might receive a 200 HTTP Response Code and API might still fail, receiving Status Code of 1. This means that the API was successfully received by the controller, however the controller returned Status Code of 1 due to error in AOS configuration.

📘

Note

In addition to HTTP Response Codes and Status Codes, you will receive a status string describing the effect on the system as ’status_str'. Possible values for “status_str”:
1)”Success” message
2) An error/warning string depending on the endpoints that are configured

 

Sequential Configuration

Before using the configuration related API endpoints to achieve an automation workflow, an important construct to keep in mind is sequential configuration. While configuring the controller you should keep in mind the sequence in which the configuration is applied. Sometimes there might be multiple endpoints that are used to configure an entity on the controller. The API should follow the correct sequence by using the API endpoints accordingly. This sequence resembles the sequence followed while configuring through the Command Line Interface (CLI).

Examples to illustrate the above caveat:

• In order to create a VLAN interface, you would first need to create a VLAN. This means you would need to first use the endpoint/object that creates a VLAN (vlan_id) and then use the endpoint/object to create an Interface VLAN (int_vlan)
• If you would like to create an SSID, respective API endpoints should be used orderly to configure the necessary Server Group, AAA profile, SSID profile, Virtual AP Profile and AP Group, as if you were configuring it through the Command Line Interface (CLI) .

If the configuration sequence is not followed as expected by the system, it will send a response with error strings or it might create incorrect configuration on the controller. Therefore, it is an important point to review the sequence while building an automation workflow.