First published: 24/Oct/2016
Last update: 31/Oct/2016
ASA REST API version: 1.3.2

REST is an acronym of Representational State Transfer (REST) API. This API provide administrators an option to perform CRUD operations which is Create, Read, Update, Delete. It fully rely on HTTPS as transport protocol and requires programming skills from administrators. But if you gain some experience its a good way of learning and getting familiar with whole new world when you more program devices than configure it.

Firewall side configuration

Before you start you need to install and enable REST API on ASA. I assume that you know how to enable HTTPS access to firewall and if you are working not in isolated lab environment this access is properly secured.

Virtual ASA (ASAv) includes the REST API image but it’s disabled by default. For physical boxes REST API is available for download on cisco.com (valid contract is required) then upload it to firewall. If you are using ASAv on Cisco VIRL you will be required to upload REST API first.

Before enabling REST API make sure that https access is properly configured and include host from which you’re going to execute the scripts. Also AAA should be configured for proper local or remote authentication for http access. Privilege level for user should be set to proper value depending what permission we want to assign. Level 3 or greater is required for monitoring requests,level 5 or greater for GET requests, and level 15 is necessary if we want to modify configuration using PUT/POST/DELETE methods.

To enable REST API image must be specified and agent enabled

rest-api image disk0:/asa-restapi-132-lfbff-k8.SPA
rest-api agent

It’s always good to verify if Agent started correctly

ciscoasa# show rest-api agent 
REST API agent is currently enabled.

In case of any problems some debugging can be enabled on ASA using

debug rest-api [agent | cli | client | daemon | process | token-auth] [error | event]

command.

Client side configuration

There are multiple ways of using REST API interface. We will go through some of them in other chapters of tutorial.

For some browsers, like Firefox, there are add-ons available you to use REST API which is useful for learning and testing. I personally use RESTClient extension for Firefox.

We will get into some theory to better understand how REST API works in different chapter. What we need to know now is:

• REST API relies on executing methods (GET, PUT, POST, DELETE and PATCH)
• Each feature that can be used via API is available under dedicated URL, the structure of URLs is hierarchical, similar to SNMP
• To each method attributes may or have to be defined and are stored in pairs containing name an value
• As a response to method we receive response code and response data tha is also stored in pairs containing name an value

So by great simplification we can compare REST API to SNMP. There is hierarchical tree-based structure we can access using methods. Each object within structure can return some values.

Lets do something to provide REST API is working by getting information about firmware version installed on firewall. To do that we will use GET method and URL http://<ip of firewall>/api/monitoring/device/components/version. We put this data into form in RESTClient plug-in in Firefox and leave Body field empty. During execution we will be prompted for credential to account that have permission to execute REST API requests.

Response consist of two parts. First is Header that is carrying information of query execution status

1. Status Code: 200 OK
2. Accept-Ranges: bytes
3. Content-Length: 217
4. Content-Type: application/json; charset=UTF-8
5. Date: Fri, 14 Oct 2016 22:49:16 GMT
6. Server: CiscoASARestApiServer
7. Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

The information we requested is encoded withing Response Body

1. {
2. “kind”: “object#Version”,
3. “selfLink”: “/api/monitoring/device/version”,
4. “upTimeinSeconds”: 7800,
5. “deviceType”: “ASA5525”,
6. “firewallMode”: “Router”,
7. “totalFlashinMB”: 8192,
8. “asaVersion”: “9.6(2)”,
9. “currentTimeinSeconds”: 1476492557
10. }

As you can see response contain multiple values identified by their names.

Of course such data can be retreived also via SNMP so you may be asking now “so why this way?” and “why can’t I use SNMP for that?”. The answer is yes you can but whole power of REST API is that you can program/script your work introducing automation. This is DevOps, this is SDN so definitely something you want to get to know 😉

REST API Documentation

Cisco provided some nice documentation of REST API including basic steps. This can be found HERE. API documentation of all supported methods is also included in REST API package that was uploaded to firewall and available via https using url https://.