Cisco ASA REST API Quick Start Guide

Request Structure

Available request methods are:

• GET – Retrieves data from the specified object.
• PUT – Adds the supplied information to the specified object; returns a 404 Resource Not Found error if the object does not exist.
• POST – Creates the object with the supplied information.
• DELETE – Deletes the specified object.
• PATCH – Applies partial modifications to the specified object.

Response Structure

Each request produces an HTTPS response from the ASA with the standard headers, response content, and status code.

The response structure can be:

• LOCATION – Newly created resource ID; for POST only—holds the new resource ID (as a URI representation).
• CONTENT-TYPE – Media type describing the response message body; describes the representation and syntax of the response message body.

Each response includes an HTTP status or error code. Available codes fall into these categories:

• 20x - A two-hundred series code indicates successful operation, including:

– 200 OK – Standard response for successful requests.

– 201 Created – Request completed; new resource created.

– 202 Accepted – Request accepted, but processing not complete.

– 204 No Content – Server successfully processed request; no content is being returned.

• 4xx - A four-hundred series code indicates a client-side error, including:

– 400 Bad Request – Invalid query parameters, including unrecognized parameters, missing parameters, or invalid values.

– 404 Not Found – The provided URL does not match an existing resource. For example, an HTTP DELETE may fail because the resource is unavailable.

– 405 Method not Allowed – An HTTP request was presented that is not allowed on the resource; for example, a POST on a read-only resource.

• 5xx - A five-hundred series code indicates a server-side error.

In the case of an error, in addition to the error code, the return response may include an error object containing more details about the error. The JSON error/warning response schema is as follows:

[

{ “code” : “string”,

“details”: “string”,

“context”: attribute name,

“level” : <Error/Warning/Info>

},

...

]

where the object properties are:

Note Changes to the ASA configuration made by REST API calls are not persisted to the startup configuration; that is, changes are assigned only to the running configuration. To save changes to the startup configuration, you can POST a writemem API request; for more information, follow the “Write Memory API” entry in the About the ASA REST API table of contents.

Usage Guidelines

Important You must include the header User-Agent: REST API Agent in all API calls and existing scripts. Use -H 'User-Agent: REST API Agent' for the CURL command.

In multi-context mode, the REST API Agent commands are available only in the System context.

Maximum Supported Configuration Size

The ASA Rest API is an “on-board” application running inside the physical ASA, and as such has a limitation on the memory allocated to it. Maximum supported running configuration size has increased over the release cycle to approximately 2 MB on recent platforms such as the 5555 and 5585.

The ASA Rest API also has memory constraints on the virtual ASA platforms. Total memory on the ASAv5 can be 1.5 GB, while on the ASAv10 it is 2 GB. The Rest API limits are 450 KB and 500 KB for the ASAv5 and ASAv10, respectively.

Therefore, be aware that large running configurations can produce exceptions in various memory-intensive situations such as a large number of concurrent requests, or large request volumes. In these situations, Rest API GET/PUT/POST calls may begin failing with 500 - Internal Server Error messages, and the Rest API Agent will restart automatically each time.

The workarounds to this situation are either move to higher-memory ASA/FPR or ASAV platforms, or reduce the size of the running configuration.

Download and Install the REST API Agent

Using the CLI, follow these steps to download and install the ASA REST API agent on a specific ASA:

Step 1 On the desired ASA, issue the copy <package> disk0: command to download the current ASA REST API package from cisco.com to the ASA’s flash memory. For example:

Step 2 Issue the rest-api image disk0:/<package> command to verify and install the package. For example:

The installer will perform compatibility and validation checks, and then install the package. The ASA will not reboot.

Enable the REST API Agent

Follow these steps to enable the ASA REST API Agent on a specific ASA:

Step 1 Ensure the correct software image is installed on the ASA.

Consult the REST API section of the ASA Compatibility Matrix ( https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) to determine which ASA image is required.

Step 2 Using the CLI, ensure the HTTP server is enabled on the ASA, and that API clients can connect to the management interface. For example:

Step 3 Using the CLI, define HTTP authentication for the API connections. For example:

Step 4 Using the CLI, create a static route on the ASA for API traffic. For example:

Step 5 Using the CLI, enable the ASA REST API Agent on the ASA. For example:

REST API Authentication

There are two ways to authenticate: Basic HTTP authentication, which passes a user name and password in every request, or Token-based authentication with secure HTTPS transport, which passes a previously created token with each request. Either way, authentication will be performed for every request. See the section, “Token_Authentication_API” in the About the ASA REST API v7.14(x) guide for additional information about Token-based authentication.

Note Use of Certificate Authority (CA)-issued certificates is recommended on ASA, so REST API clients can validate the ASA server certificates when establishing SSL connections.

Command Authorization

If command authorization is configured to use an external AAA server (for example, aaa authorization command < TACACS+_server >), then a user named enable_1 must exist on that server with full command privileges.

If command authorization is configured to use the ASA’s LOCAL database ( aaa authorization command LOCAL), then all REST API users must be registered in the LOCAL database with privilege levels that are appropriate for their roles:

• Privilege level 3 or greater is required to invoke monitoring requests.
• Privilege level 5 or greater is required for invoking GET requests.
• Privilege level 15 is necessary for invoking PUT/POST/DELETE operations.

Configure Your REST API Client

Follow these steps to install and configure a REST API client on your local-host browser:

Step 1 Acquire and install a REST API client for your browser.

For Chrome, install the REST client from Google. For Firefox, install the RESTClient add-on. Internet Explorer is not supported.

Step 2 Initiate the following request using your browser:

If you receive a non-error response, you have reached the REST API agent functioning on the ASA.

If you are having issues with the agent request, you can enable display of debugging information on the CLI console, as described in Enabling REST API Debugging on the ASA.

Step 3 Optionally, you can test your connection to the ASA by performing a POST operation.

For example:

Provide basic authorization credentials ( < username >< password >), or an authentication token (see Token Authentication for additional information).

Target request address: https://< asa management ipaddress >/api/objects/networkobjects

Body content type: application/json

Raw body of the operation:

{

"kind": "object#NetworkObj",

"name": "TestNetworkRangeObj",

"host": {

"kind": "IPv4Network",

"value": "12.12.12.0/24"

}

}

You can now use the ASA REST API to configure and monitor the ASA. Refer the API documentation for call descriptions and examples.

About Fully Restoring a Back-up Configuration

Restoring a full back-up configuration on the ASA using the REST API will reload the ASA. To avoid this, use the following command to restore a back-up configuration:

{

"commands":["copy /noconfirm disk0:/< filename > running-config"]

}

Where < filename > is backup.cfg or whatever name you used when backing up the configuration.

JavaScript

Using a JavaScript file requires installation of node.js, which can be found at http://nodejs.org/. Using node.js, you can execute a JavaScript file, typically written for a browser, like a command-line script. Simply follow the installation instructions, and then run your script with node script.js.

Python

The Python scripts require you to install Python, available from https://www.python.org/. Once you’ve installed Python, you can run your script with python script.py username password.

Perl

Using the Perl scripts requires some additional set-up—you need five components: Perl itself, and four Perl libraries:

• Perl package, found at http://www.perl.org/
• Bundle::CPAN, found at http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
• REST::Client, found at http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
• MIME::Base64, found at http://perldoc.perl.org/MIME/Base64.html
• JSON, found at http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Here is an example of bootstrapping Perl on a Macintosh:

$ sudo perl -MCPAN e shell

cpan> install Bundle::CPAN

cpan> install REST:: Client

cpan> install MIME::Base64

cpan> install JSON

After installing the dependencies, you can run your script using perl script.pl username password.

 

Syntax Description

 

Usage Guidelines

If you do not provide a specific component keyword (that is, if you simply issue the command debug rest-api), debug messages are displayed for all component types. If you do not provide either the event or error keyword, both event and error messages are displayed for the specified component. For example, debug rest-api daemon event will show only event debug messages for API Daemon-to-Agent communications.

 

Related Commands

342001

Explanation The REST API Agent must be successfully started before a REST API Client can configure the ASA.

Recommended Action None.

342002

Explanation The REST API Agent could fail to start or crash for various reasons, and the reason is specified.

• reason —The cause for the REST API failure

Recommended Action The actions taken to resolve the issue vary depending on the reason logged. For example, the REST API Agent crashes when the Java process runs out of memory. If this occurs, you need to restart the REST API Agent. If the restart is not successful, contact the Cisco TAC to identify the root cause fix.

342003

Explanation A failure notification from the REST API Agent has been received and a restart of the Agent is being attempted.

Recommended Action None.

342004

Explanation The REST API Agent has failed to start after many attempts.

Recommended Action See syslog %ASA-3-342002 (if logged) to better understand the reason behind the failure. Try to disable the REST API Agent by entering the no rest-api agent command and re-enable the REST API Agent using the rest-api agent command.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1721R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

© 2014-2018 Cisco Systems, Inc. All rights reserved.