What is REST API
REST stands for REpresentational State Transfer and API for Application Programming Interface.
In short, it is an interface to interact with a system using Web Serives.
As network engineers, we know what CLI commands are and how to use them in an SSH session. REST commands are similarly sent, but in a web session. Specifically, we embed them in the URI of our request to the server (or switch in our case). The protocol used to connect to the switch will be HTTP(S).
HTTP is not to be confused with REST. Just like CLI commands are not the same as SSH, REST commands are not the same as HTTP. HTTP is just used as communication protocol.
The commands look like folders of a web server and we will add attributes to them to specify them. Then we will also add the data needed for the switch to perform the commands we sent.
What is supported?
In this tutorial, we will connect to the ArubaOS-S REST API.
This API is fundamentally different from the ArubaOS-CX API, which I will cover in a future post.
For the switch to support REST API calls, we need a supported switch, a current firmware. It is enabled by default.
The following switches are supported at the time of writing:
- Aruba 5400R zl2 Switch Series
- Aruba 3810M Switch Series
- Aruba 2920 Switch Series
- Aruba 2930M Switch Series
- Aruba 2930F Switch Series
- Aruba 2540 Switch Series
- Aruba 2530 Switch Series
I will use the following switch and firmware in my demonstrations:
- Aruba 2540 (JL354A)
Note that SSL certificates are already generated on my switch.
What can we do?
We can do almost everything via the REST API, what we can do via command line.
To do that we have a four general methods:
- returns information for that URI
- Create new data
- Update existing data
- Delete data
Combined with an URI this will be our method of configuring the switch.
About the URI
The URI is build out of these components:
- Hostname / IP
- REST version
We can then use post to create a new session or delete to delete the session / logout.
Version 7 is the newest version of the API and we will use it here. For more information about the version read the documents on asp.arubanetworks.com
How to connect
We connect using URI commands and the HTTPS protocol. There are plenty of ways to do that, f.e. using the cURL command-line tool or PowerShell.
For my first tutorial, I will use Postman for a simple overview of what is happening.
Later I will use Python 3 with the requests module to be able to process the data in more complex ways later.
Enable / Disable REST API
- The REST API is enabled by default.
- To access it, web-management must stay enabled and we need access to ports tcp/80 using HTTP or tcp/443 using HTTPS.
- IPv6 is not supported.
- OOBM interfaces are supported.
To disable the REST API, we need to connect to the CLI and either disable the web-management alltogether:
Switch_2540(config)# no web-management Switch_2540(config)# no web-management ssl Switch_2540(config)# show rest-interface REST Interface - Server Configuration REST Interface : Enabled REST Operational Status : Down HTTP Access : Disabled HTTPS Access : Disabled
Or we just disable the rest-interface, so that the normal web-management can stay enabled:
Switch_2540(config)# web-management ssl Switch_2540(config)# no rest-interface Switch_2540(config)# show rest-interface REST Interface - Server Configuration REST Interface : Disabled REST Operational Status : Down HTTP Access : Disabled HTTPS Access : Enabled SSL Port : 443
To enable it, either HTTP or HTTPS web-management and the rest-interface must be up:
Switch_2540(config)# rest-interface Switch_2540(config)# web-management ssl Switch_2540(config)# show rest-interface REST Interface - Server Configuration REST Interface : Enabled REST Operational Status : Up REST Session Idle Timeout : 120 seconds HTTP Access : Disabled HTTPS Access : Enabled SSL Port : 443