Tutorial: AOS-CX RESTful API and Postman
07-16-2019 09:53 PM
Here are a few examples of how to interact with AOS-CX's RESTful API using Postman. Let me know if you have any questions, comments, ideas, or would like me to explain anything further.
AOS-CX capable switch (also works with virtual switch)
Initial Switch Configuration
rest access-mode read-write enabled
Mgmt IP: 192.168.121.2/24
Administrative User: Admin:Aruba123
Administrative User: apiadmin:Aruba123
vlan 7 undefined
interface 1/1/4 undefined
Initial Postman Configuration
Environment's global variable name "host" set to "192.168.121.2"
Feel free to change any of these settings but just be aware this is the assumed configuration for these examples to work out of the box. Let me know if you have any issues here. I can further explain how to customize your Postman requests to align with your switch's config.
Importing the Examples
- Open Postman and select the "Import" button, at the top left of the application, to the right of the "New" button.
- Select "Import from Link"
- Paste the following link in and click "Import" https://www.getpostman.com/collections/e2d70f29cfbb0b0fbb90
Examples & Descriptions
If the import went as expected, you'll now see a collection of 13 requests labelled "Aruba Andy's AOS-CX Collection" on the left hand side of your Postman app.
This is a POST request that simply logs into the switch using credentails "appadmin" with password "Aruba123". Feel free to change this to align with whatever login credentials you want to use. You can use CLI command "show events restd | include session" on the switch to see the login events from the switch.
This is a POST request that logs the user out. It's always good practice to send a logout request to keep your sessions clean and not rely on idle time-outs to logout your API user.
AOS-CX: Show UP Interfaces
This is a self explanitory GET request. Bring up a few interfaces from the CLI and see this request perform as you'd expect. This could be a basic building block for automation, so it's good to see it work first hand.
AOS-CX: Show Running-Config Example
This GET request is probably the most useful example I can give you as someone learning these concepts. If you're ever unsure of how to configure a setting in API vs CLI, configure the switch in CLI then run this request. You can literally copy and paste the result of this request into the body of the next example, "AOS-CX: Upload Full-Config" and it will overwrite the old config exactly as you configured it in the CLI. This can be very useful for custom building configurations or getting an insight to the formatting differences between API & CLI.
AOS-CX: Upload Full-Config
This PUT request does exactly as it's described. It will effectively replace the config on the switch with that in the body of this request. Be careful using this out of the box! I used the virtual AOS-CX switch with the switch configuration assumptions listed above. It will overwrite your current config. I suggest playing with the previous example and comparing its output with the body of this request, then replacing the body of this request and then trying it out.
AOS-CX: Traceroute Example
This request is exactly the same as the Traceroute tool in the GUI interface of the switch under the "Diagnostics" section.
AOS-CX: Ping Example
Just like the above Traceroute example, this is the same as the Ping tool in the "Diagnostics" section of the GUI of the switch.
VLAN & Interface Demo
I created these requests to show off what a workflow of creating vlan7, assigning it to interface 1/1/4 and bringing the interface up might look like. I've done this to outline a potentially unexpected outcome of using API vs CLI. I'll explain in further detail below.
AOS-CX: Create vlan7
As described in the name, this creates vlan7. Check out the body of this POST request to see the details. Feel free to run a "show run" on the CLI to see how each of these requests interact with the switch from the perspective of CLI.
AOS-CX: Map 1/1/4 to vlan7
This is the tricky one. If your interface hasn't ever been defined in the switch, this works just like you'd expect it to. Interestingly though, if you run it and the interface has been defined in the config, this will fail. This can be frustrating if you're not expecting it. This has to do with the way the switch maps a physical interface to a logical port. You can find more information on this specific topic in the "ArubaOS-CX REST API Guide for 10.1", page 42, section "Considerations for ports and interfaces".
AOS-CX: Review 1/1/4
This GET request is an example taken directly from the ArubaOS-CX Rest API Guide, on page 75.
AOS-CX: Bring 1/1/4 up
This PUT request is an example of editing an interface, instead of 'creating' it like we did in the "map 1/1/4 to vlan7" example.
AOS-CX: Delete vlan7
This is an example using the DELETE method to get rid of vlan7. See what happens if you delete vlan7 while its still defined in interface 1/1/4. Does this function like it would if you deleted it in the CLI? Does it even let you delete it if its defined somewhere?
AOS-CX: Reset Switch Config
This is a duplicate of the above "Upload Full-Config" example. This is just an easy way to get everything back to the state it was in before we ran these requests.
Re: Tutorial: AOS-CX RESTful API and Postman
08-06-2019 03:41 AM
PowerArubaSW: Powershell Module to use Aruba Switch API for Vlan, VlanPorts, LACP, LLDP... More info
PowerArubaCP: Powershell Module to use ClearPass API (create NAD, Guest...) More info
PowerArubaCX: Powershell Module to use ArubaCX API (get interface/vlan/ports info)
PowerArubaIAP: Powershell Module to use Aruba Instant AP
ACMP 6.4 / ACMX #107 / ACCP 6.5