Release Notes for the Cisco ASA Series REST API, Version 7.13(x)
Installing and Enabling the ASA REST API Agent
New Features in ASA REST API 7.13(x)
Obtain Documentation and Submit a Service Request
First Published: March 21, 2016
Last Updated: September 25, 2019
This document contains release information for Cisco ASA REST API version 7.13(x).
Note: Following the release of ASA REST API version 1.3.2-346, the API version numbering scheme was changed to match Cisco ASDM versioning.
For information about REST API software and hardware requirements and compatibility, see Cisco ASA Compatibility.
Note: The ASA 5506-X series does not support concurrently running the REST API and the FirePOWER module Version 6.0 or later. If necessary, disable the ASA REST API using the “no rest-api agent” command.
The REST API Agent is published individually with other ASA images on cisco.com. For physical ASAs, the REST API package must be downloaded to the device’s flash and installed using the “rest-api image” command. The REST API Agent is then enabled using the “rest-api agent” command.
With a virtual ASA (ASAv), the REST API image must be downloaded to the “boot:” partition. You must then issue the “rest-api image” command, followed by the “rest-api agent” command, to access and enable the REST API Agent.
You can download the appropriate REST API package for your ASA or ASAv from software.cisco.com/download/home. Locate the specific Adaptive Security Appliances (ASA) model and then choose Adaptive Security Appliance REST API Plugin.
The REST API Agent is a Java-based application. The Java Runtime Environment (JRE) is bundled in the REST API Agent package.
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.
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.
Restoring a full back-up configuration on the ASA using the REST API will reload the ASA. This is a limitation which will be addressed in a future release.
As an alternative, follow these steps to restore a full back-up:
1. Open the ASA REST API Documentation & Console page.
2. Use the POST command on the CLI tab with the following payload:
where < filename > is backup.cfg or whatever name you used when backing up the configuration.
The target request address is https://< asa_management_ipaddress >/api/cli (for example, https://198.51.100.12/doc/#feature/cli_POST); the response content type is application/json.
The open and resolved bugs for this release are accessible through the Cisco Bug Search Tool. This web-based tool provides you with access to the Cisco bug tracking system, which maintains information about bugs and vulnerabilities in this product and other Cisco hardware and software products.
Note: You must have a Cisco.com account to log in and access the Cisco Bug Search Tool. If you do not have one, you can register for an account.
For more information about the Cisco Bug Search Tool, see the Bug Search Tool Help & FAQ.
For information on the end-user license agreement, go to http://www.cisco.com/go/warranty.
For additional information on the ASA, see Navigating the Cisco ASA Series Documentation.
For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What’s New in Cisco Product Documentation at: http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html.
Subscribe to What’s New in Cisco Product Documentation, which lists all new and revised Cisco technical documentation as an RSS feed and delivers content directly to your desktop using a reader application. The RSS feeds are a free service.