I've created a Postman request collection of all the API's in the API documentation for Airwave and I figured I would share with anyone interested! Below is a tutorial on how to import the collection and a brief overview of all of the requests in the collection and descriptions of most of their outputs (I got tired of writing everything out mid-way through). Let me know if you have any questions, comments, ideas, or would like me to explain anything further.
Prerequisites
Postman v7.6.0
Airwave Appliance - Virtual or HW - I used v8.2.9.1 but this will still work on older versions. Just check the API documentation on your version by navigating to your appliance and appending "/api" to the end. https://{{location-of-your-airwave}}/api
Initial Airwave Configuration
My Postman workspace assumes an admin account named "apiadmin" with password "Aruba123!" exists and assumes no security or obscurity in the login script. Feel free to change or harden as desired/required for your environment.
Initial Postman Configuration
Create a new workspace, I named mine "Aruba Airwave" with the summary "Workspace for testing and validating Airwave API queries."
Then from the "Manage Environments" section create two new Globals, one named "host" with the initial and current value of your Airwave server. This global variable is used in all of the connection URL's so you don't have to modify all 36 requests with the location of your appliance. Instead each navigate to "https://{{host}}/" so you only have to change it i one place.
For the second global variable name it "session_token" and leave the initial and current values blank. We'll use this variable to store the unique session token Airwave requires for authentication when we run any POST requests. I'll explain that more in the "AMP: Login" request.
Importing the Examples
- In the Postman main screen select the "Import" button, at the top left of the application, to the right of the "New" button. (alternatively File > Import from the drop down)
- Select "Import from Link"
- Paste the following link in and click "Import" https://www.getpostman.com/collections/06f2d2b7ed834662dfc1
- You should now see a collection of 36 requests across 5 folders under the collection "Aruba Andy's Airwave Collection". Let me know if this doesn't work. I can throw the raw import into a pastebin and share it here.
Requests & Descriptions
AMP: Login
We'll need to run this POST request first in order to get the session cookie and token we need to authenticate us to use any of the other POST requests (it seems like just the cookie is good enough to successfully run GET requests). Per the Airwave 8.2.8 API Guide we see that we need to supply "credential_0" and "credential_1" as username and password respectively. So if you click on the AMP: Login request then click "body" you'll see we're supplying credentials ampadmin/Aruba123! and an optional destination value (that I don't think does anything, but I made it drive to "/api" anyway).
Postman automatically handles the cookie but we need to capture the "X-BISCOTTI" token to use in the other requests, so if you click on "Tests" you'll see this line:
postman.setGlobalVariable("session_token",postman..getResponseHeader("X-BISCOTTI") );
This tells Postman to get the response header "X-BISCOTTI" from the request and store it in our global variable "session_token". In all of the POST requests in this collection, you'll notice we feed this token into the header in order to get them to successfully run. If you run this request then go back into the global variables section where we defined “session_token”, you’ll see its current value is now populated with our X-BISCOTTI token.
Here is a list of what these requests return or do and a short description as I understand it (correct me if I’m wrong on any of this!)…
Query API’s >
AMP Stats
<alerts> # of alerts on the appliance, same as on the main page of the GUI.
<audit_disabled> # of devices with their audit set to ‘Monitor Only’. You can set this inside Airwave by navigating to Groups, then clicking edit on a group and toggling the “Audit Configuration on Devices” option under “Basic” to off. I had 6 devices in the group I modified, when I toggled the setting to off and applied the API came back with 6 (all devices in the group). When it was set to on I got a return of 0.
<client_count> # of clients, same as on the GUI.
<configuration_unknown> # of devices with an unknown configuration.
<down> # of devices Airwave sees as down.
<down_wired> # of down devices Airwave sees as wired and down.
<down_wireless> # of down devices Airwave sees as wireless and down.
<mismatched> # of devices Airwave sees having mismatched configs.
<name> Name of your Airwave appliance.
<new_count> New devices, same as in the GUI.
<rogue> Rogue device count, same as GUI.
<severe_alerts> # of severe alerts. I think this is connected to triggers and their severity but I’m not sure where “severe” lands in normal/warning/minor/major/critical.
<up> # of devices Airwave sees as up.
<up_wired> # of up devices Airwave sees as wired and up.
<up_wireless> # of up devices Airwave sees as wireless and up.
<vpn_all_users> # of all currently connected VPN users.
<vpn_count> # of VPN connections currently connected.
AMP Stats w/ Options
Same as AMP Stats but I’ve added the query parameters listed in the API documentation.
Folder List
<folder id=”#”> The ID of the folder
<bandwidth_in> I’m not sure if this is total kbps over the lifetime of this folder or what. My lab instance of Airwave doesn’t have enough data to make an educated guess.
<bandwidth_out> Unknown.
<client_count> # of clients in the folder
<down> # of devices down in the folder
<mismatch> # of devices with mismatched config in the folder.
<name> Name of the folder.
<up> # of devices up in the folder.
<vpn_client_count> # of VPN clients connected in the context of that folder.
Folder List w/ Options
Same as the above but I added the optional query parameter “id”, so you can pull up just one folder based on its ID.
Catalog Repository
Provides a list of all device types and all of their possible radio configurations. I’m not going to list everything in here. Feel free to run the request and scroll the results though. Since the request is a GET it is only getting data and not changing anything.
Alert List
Returns a list of active alerts. At the time of writing this I didn’t have any alerts so mine resulted in just the xml framework and nothing inside it.
AP List
Some of these variables are context specific so for example, you won’t see the AP and radio info on a controller.
< ap id=”#”> Shows the ID of the AP (or device, this can be a controller too).
<client_count> Clients connected to the device.
<device_category> This will show if it’s a controller or AP.
<firmware> Current firmware on the device. For example, in my environment ap id=1 is my 7008 controller and it’s running 8.5.0.0.
<Group id=”#”> This shows what group the device is in, and it’s group ID.
<is_up> true if up false if down.
<lan_ip> IP address of device
<lan_mac> MAC address of device
<last_contacted> Returns the last contacted time/date in Epoch timestamp. epochconverter.com converts this, as an example of how to read it.
<last_reboot> Returns the last rebooted time/date in the same Epoch format.
<mfgr> Shows manufacturer of device. Unsurprisingly all mine says “Aruba”.
<model id=”#”> Shows the model ID and short name (I think?) of the device. As an example my 7008 shows <model id=”670”>7008</model>, my AP 115 shows <model id=”474”>AP 115<model>
<monitor_only> returns true or false.
<name> Name of the device as defined by the infrastructure. I named my AP 115 “LabTest” and that’s what I see in this field.
<operating_mode> will show if it’s a remote AP, campus AP, etc.
<planned_maintenance_mode> Returns true or false, this is defined by the maintenance mode setting in Airwave. An example of what maintenance mode is and why to use it would be, as an example on an AP, so the AP stops flooding traps and syslog messages to the network during a deployment or scheduled maintenance.
<radio index=”#”> This begins details on an AP’s radios. Channel, enabled, transmit power, operational_mode, etc.
<reboot_count> I think this is the amount of reboots the AP did until it successfully joined the network.
<serial_number> Serial # of the device. This could be great for automating inventory.
<snmp_uptime> Up time of the device on snmp, in seconds.
<ssid> SSID(s) the device is broadcasting.
<syscontact> Contact info of the device (if defined).
<syslocation> Location info of the device (if defined).
AP List w/ Options
Same as AP List but I’ve added the optional query parameters so you can query specifically by folders, groups, controllers or ID’s.
AP BSSID List
This outputs a list of all the AP’s in Airwave and their BSSID information, channel, index, radio_mac, radio_type, text, etc.
AP BSSID List w/ Options
This request is the same as AP BSSID List but I’ve added the optional query parameters, much like the other “w/ Options” requests, you can further define what you’re looking for and only pull that data specifically instead of having to drag-net the API and parse it all out on the other side.
AP Detail
This request outputs a lot more than just AP details. If you’ve got a controller, it’ll output interface details including name, status, port index, mac address, average bandwidth (avg_bw_in/out) in and out & type. This is also where you’ll find what clients are attached to which AP’s and details for those clients - like role’s, rssi, signal, snr, vendor of device if known, name’s IP’s, etc.
Note the neighbour AP’s with <neighbor_type> as “rogue”. You will use the ID in <neighbour_ap id=”#”> in the Rogue Detail request to look up the details on the potential rogue.
AP Detail w/ Options
As described with above “w/ Options” requests, this request just adds the optional query parameters to search by folder, group, controller, etc.
AP Log
This request outputs the log entries for the device. For example if you define an AP ID and limit (lines to return) to 5 in the query parameters, it’ll output the date of the message, the actual message and the user that wrote the log. I queried one of my AP’s and it shows its discovery, its authorization, configuration change, up status and status update of ‘OK’.
Rogue Detail
This request outputs all the details for potential rogues. You’ll find the rogue ID in the AP Detail <neighbor_type> “rogue” section and can then use the associated neighbor_ap ID in this request. This will give you which AP’s have seen the potential rogue, discovery times, rssi, security, signal, ssid and type of discovery details.
Client Detail
This query is best used in conjunction with the Client Search request, found in the Search API’s folder. This request requires a full mac address of the client to return results. The client details include the following..
<client mac=””> Client’s MAC address
<ap id=”#”> AP ID and name of AP it’s connected to
<assoc_stat> true/false – if the client is associated.
<auth_stat> true/false – if the client is authenticated.
<connect_time> timestamp of when it connected.
<device_type> Name of the device if available.
<lan_elements> host name, IP address, etc.
<radio_mode> Radio mode the device is using.
<rssi> Self-explanatory.
<signal> Self-explanatory.
<snr> Self-explanatory.
<ssid> SSID it’s connected to.
<username> username (shows IP address if username not applicable)
<vendor> Vendor of device if available
<vlan> vlan the device is on.
VisualRF Config
This outputs the current VisualRF config.
User Info
This outputs the currently logged in user details. In my case, I see the details for user “apiadmin” since that’s what I’m using to interact with the API.
Device RRD Info
RRD = Round-Robin Database. That’s about as far as I know about this. Lots of device info in here though.
Client RRD Info
Same as Device RRD. I’m not sure what this is for further than being part of the inner workings of Airwave.
Configuration API’s >
Change Set
The documentation says this enables an external application to post “change sets” for AP and radio parameters but I can’t find the required parameter “site_id” to make it work.
Guest User: Create User
This request is the same as in the Airwave API documentation example. It creates a guest user named “Bob Acme” with username “bob_acme”.
Guest User: Get User
This request finds the user by username “bob_acme” and outputs the user’s details.
Guest User: Get All Users
This request outputs all users. If you’ve run the Guest User: Create User request, you’ll see Bob Acme in the results.
Guest User: Update User
This request updates Bob Acme’s account status to disabled. You can run the Guest User: Get User request again and see the change made to <enabled>.
Guest User: Delete User
This request deletes the user entry for Bob Acme. You’ll see this succeeded with the response <deleted>1</deleted>. You can also run the Guest User: Get All Users after this is run and see that he’s no longer in the database.
Modify Template Variables
This POST request updates an existing template’s variables. I used the same example for this request as is in the API guide. Also there is a list of variables you can change and a brief description of the variable in this list: https:// {{location-of-your-airwave}}/static/api/template_variable_list.txt
Import AP Whitelist
This request requires a CSV file as perimeter as input and I haven’t figured out how to make that work with Postman yet. I’ll update this section if I figure it out. https://learning.getpostman.com/docs/postman/collection_runs/working_with_data_files/
Deauthenticate Client
This request will deauthenticate clients who are connected to a device which supports the deauth operation. The device must also be in “Manage Read/Write” mode or it will return the message “Device is in monitor-only mode.” With a status of “failed”. I’ve added more than one example mac address to illustrate the ability to use the request with more than one entry. This will work just as well if you only need to use one mac address query parameters.
Down Status Message
Documentation for this request says it enables an external application to set AMP’s down status message on individual devices or groups of devices. I ran this request as on one of my lab access points by finding its AP ID from the AP List request and supply this request with the ap_id and down_status_message as “Scheduled+maintenance+until+Friday+at+12pm” and ran the request. The request came back with <ap id=”3” status=”succeeded” />. I unplugged the AP and in Airwave the system event shows “Status changed to ‘AP is no longer associated with controller (Scheduled maintenance until Friday at 12pm)’”.
Search API’s >
AP Search
Use this request if you’re looking for a particular AP. The query perimeter can accept partial or complete MAC addresses or IP addresses. This might be useful if you’re looking for all the AP’s in a subnet. For example if your query value is “192.168.1” it’ll return all the AP’s with the IP address 192.168.1.*.
Client Search
This is the same concept as the AP Search request. It can also find partial or full MAC or IP addresses.
VPN User Search
I assume the same for this as I haven’t actually used it in an environment with active VPN sessions.
Report API’s >
Latest Report
This request pulls the most recent run of a specific report and presents it in XML format. To find the ID of the report you want to feed into this request you can edit the report in Airwave and look at the URL. It’ll have “definitions_edit=1&id=#” in the URL. Just use that id #.
Batch Execute AP Commands API’s >
Batch Execute AP Command
This request sends batch commands to APs and captures the results of the commands. In the body of this POST request you’ll see where you define ap id, ap controller id, ap ap_group_id, and ap_folder_id for the device(s) you want to send the commands to. The commands to be sent to the AP’s in this example are found in the cmds=”” section of the body, near the top of the section. In this case it’ll be “show version” and “show aps”.
Batch Execute AP Command Result
This shows the result of the Batch Execute AP Command. This is the same as just navigating to https://{{host}}/api/batch_command_execute_result in a web browser.