First Published: May 26, 2021

Release Notes for the Cisco ASA Series REST API

First Published: May 26, 2021

This document contains release information for Cisco ASA REST API.


Note

Following the release of ASA REST API version 1.3.2-346, the API version numbering scheme was changed to match Cisco ASDM version numbering.

System Requirements

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.

Installing and Enabling the ASA REST API Agent

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.

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, 5585, and 4100 Series.

.

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 Back-up 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:

Procedure

Step 1

Open the ASA REST API Documentation & Console page.
Step 2

Use the POST command on the CLI tab with the following payload:

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

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.

New Features

This section lists new features for each release.

New Features in ASA REST API 7.16(x)

Released: May 26, 2021

No new features were added. This release is only a renumber release to accompany ASA 9.16.

New Features in ASA REST API 7.15(x)

Released: November 5, 2020

No new features were added. This release is only a renumber release to accompany ASA 9.15.

New Features in ASA REST API 7.14(x)

Released: April 1, 2020

ASA REST API Version 7.14(1) contains bug fixes only; no new features were added.

New Features in ASA REST API 7.13(x)

Released: September 25, 2019

ASA REST API Version 7.13(1) contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(x)

New Features in ASA REST API 1.3(2)-346

Released: February 28, 2019

ASA REST API image 1.3.2-346 is a special patch that provides key changes related to authorization, and addresses a few bugs.

This release is backward compatible and upgrading to this version is recommended.

ASA REST API image 1.3.2-346 or later is the minimum required version for compatibility with these ASA versions:

  • 9.12.1 or later

  • 9.10.1.11 or later

  • 9.6.4.22 or later

  • 9.4.4.31 or later

New Features in ASA REST API 1.3(2)-325

Released: August 8, 2018

ASA REST API Version 1.3(2)-325 contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(2)-320

Released: July 16, 2018

ASA REST API Version 1.3(2)-320 contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(2)-308

Released: May 18, 2018

ASA REST API Version 1.3(2)-308 contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(2)-221

Released: March 9, 2018

ASA REST API Version 1.3(2)-221 contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(2)-200

Released: November 21, 2017

ASA REST API Version 1.3(2)-200 contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(2)-100

Released: February 16, 2017

The response type of /api/certificate/details was changed from the CertificateDetails object to a list of CertificateDetails. Scripts utilizing this API will need to be modified accordingly.

New Features in ASA REST API 1.3(2)

Released: August 22, 2016

ASA REST API Version 1.3(2) contains bug fixes only; no new features were added.

New Features in ASA REST API 1.3(1)

Released: March 21, 2016

The following are the new features for ASA REST API Version 1.3(1).

  • Application Protocol inspection—We added support for the ESMTP and SNMP protocol inspections:

  • Certificate Management—We added support for generating and managing key pairs, identity certificates and Certificate Authority (CA) certificates

  • TLS Proxy—We added support for TLS Proxy configuration.

New Features in ASA REST API 1.2(x)

New Features in ASA REST API 1.2(2)200

Released: February 9, 2016

This release provides a fix for the following bug: CSCux92088 Increase the limit of bulk api request entries to 1000.

New Features in ASA REST API 1.2(2)

Released: November 30, 2015

We added support for the following features:

  • Smart Licensing

  • IP Audit

  • Additional inspections: FTP, NetBIOS, RTSP, SIP, SQL*Net

  • ASA serial number querying

New Features in ASA REST API 1.2(1)

Released: August 11, 2015

We added support for the following features:

  • Monitoring support for multi-context mode

  • DHCP server and relay agents

  • DNS

  • Protocol Timeout (PTO)

  • GTP

  • IP Options

New Features in ASA REST API 1.1(x)

New Features in ASA REST API 1.1(2)

Released: July 14, 2015

We introduced support for the ASA security module on the Firepower 9300.

New Features in ASA REST API 1.1(1)

Released: March 23, 2015

The following are the new features for ASA REST API Version 1.1(1)/ASDM Version 7.4(1).

  • Token-based authentication (in addition to existing basic authentication)—Client can send log-in request to a specific URL; if successful, a token is returned (in response header). Client then uses this token (in a special request header) for sending additional API calls. The token is valid until explicitly invalidated, or the idle/session timeout is reached.

  • Limited multiple-context support—The REST API agent can now be enabled in multi-context mode; the CLI commands can be issued only in the system context.

    Pass-through CLI API commands can be used to configure any context, as follows.

    https://<asa_admin_context_ip>/api/cli?context=<context_name>

    If the context parameter is not present, it is assumed that the request is directed to the admin context.

  • Application Protocol inspection—We added support for the following inspections:

    • DNS over UDP

    • HTTP

    • ICMP

    • ICMP ERROR

    • RTSP

    • DCERPC

    • IP Options

  • Connection limits

  • Backup and restore

  • NTP

  • Write memory—We added support for saving the running configuration (write memory ).

New Features in ASA REST API 1.0(1)

Released: December 18, 2014

The following are the new features for ASA REST API Version 1.0(1)/ASDM Version 7.4(1).

  • We introduced support for the following ASA features:

    • Interface configuration

    • Licensing (Permanent and Activation Key Licenses), Shared Secret License

    • Management Access

    • Static Routing

    • AAA

    • Access Rules

    • NAT (Twice NAT and Object NAT)

    • Service Policy

    • Objects (network objects/groups, service objects/groups, time ranges, security groups)

    • Failover

    • Logging

    • Site-to-Site VPN

    • Monitoring

  • Bulk API—The Bulk API is optimal for loading or deleting large sets of data.

  • CLI pass-through or Generic CLI command executor API—Supports pass-through CLI for ASA features that are not supported in the API.

Open and Resolved Bugs

The open and resolved bugs 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. If you do not have a Cisco support contract, you can only look up bugs by ID; you cannot run searches.

For more information about the Cisco Bug Search Tool, see the Bug Search Tool Help & FAQ.

Open and Resolved Bugs in 7.16(x)

There are no open or resolved bugs for this release.

Open and Resolved Bugs in 7.15(x)

There are no open or resolved bugs for this release.

Open and Resolved Bugs in 7.14(x)

Open Bugs in 7.14(1)

None.

Resolved Bugs in 7.14(1)

Table 1. Resolved Bugs in 7.14(1)

Bug ID

Title

CSCvr42559

Not able to push TCP TIMEOUT info under policy-map using REST API

CSCvr62864

Duplicate objects error while configuring objects and ACL using Rest API feature.

Open and Resolved Bugs in 7.13(x)

Open Bugs in 7.13(1)

None.

Resolved Bugs in 7.13(1)

Table 2. Resolved Bugs in 7.13(1)

Bug ID

Title

CSCvn22345

ASA Rest-API -CT1660 SEC-WEB-XSS-2: Prevent cross-site scripting vulnerabilities in doc page

CSCvn31661

Missing X-Content-Type-Options in Rest-API header

CSCvo25798

Empty responses for the REST-API GET queries even status code is 200

CSCvo25812

500 internal server error while trying to add user using REST-API

CSCvq57500

REST-API: Block Spyker/5512/5515 device types

Open and Resolved Bugs in 1.3(x)

The following topics list the open and resolved bugs for the various 1.3(x) versions.

Open and Resolved Bugs in 1.3(2)-346

Open Bugs in 1.3(2)-346
Table 3. Open Bugs in 1.3(2)-346

Bug ID

Title

CSCvn22345

ASA Rest-API -CT1660 SEC-WEB-XSS-2: Prevent cross-site scripting vulnerabilities in doc page

CSCvn31661

Missing X-Content-Type-Options in Rest-API header
Resolved Bugs in 1.3(2)-346
Table 4. Resolved Bugs in 1.3(2)-346

Bug ID

Title

CSCvp32185

DOC - "User-Agent: REST API Agent" in all the REST calls from is now required

CSCvi96137

Rest agent unable to lookup privilege for usernames with '/' characters

CSCvm25757

Rest-api: Deleting network object deletes the auto NAT entry but rest-API shows the nat in GETALL

CSCvm67174

REST-API on ASA fails with SERVER ERROR when pushing extensive group-policy configuration

CSCvn21953

Need to check the versioning between ASA 9.9.2 and ASA 9.10.1

CSCvk33889

Bulk API returns different code for some requests

Open and Resolved Bugs in 1.3(2)-325

Open Bugs in 1.3(2)-325
Table 5. Open Bugs in 1.3(2)-325

Bug ID

Title

CSCvk61568

ASA REST-API only one extended access-list returned

CSCvo31847

REST-API: restore POST reloads the ASA.
Resolved Bugs in 1.3(2)-325
Table 6. Resolved Bugs in 1.3(2)-325

Bug ID

Title

CSCvk57255

“Specified remark does not exist\n” shown when body of the PATCH method contains multiple actions

Open and Resolved Bugs in 1.3(2)-320

Open Bugs in 1.3(2)-320
Table 7. Open Bugs in 1.3(2)-320

Bug ID

Title

CSCvk06041

Cannot create a rule via REST-API that references a non-existent service object type of “tcp-udp”

Resolved Bugs in 1.3(2)-320
Table 8. Resolved Bugs in 1.3(2)-320

Bug ID

Title

CSCvk05506

“Specified remark does not exist\n” error message shown if a rule with multiline remarks is changed

Open and Resolved Bugs in 1.3(2)-308

Open Bugs in 1.3(2)-308
Table 9. Open Bugs in 1.3(2)-308

Bug ID

Title

CSCvj99455

REST-API Login: Fallback Authentication does not work
Resolved Bugs in 1.3(2)-308
Table 10. Resolved Bugs in 1.3(2)-320

Bug ID

Title

CSCvh50326

REST API - not supporting user-configured OG protocol argument for PATCH method

CSCvg17528

ASA REST API Agent failed, reason: OUTOFMEMORY_CONDITION_OCCURED

CSCvg33026

Increase max heap memory allocation

Open and Resolved Bugs in 1.3(2)-221

Open Bugs in 1.3(2)-221
Table 11. Open Bugs in 1.3(2)-221

Bug ID

Title

CSCvi26193

REST-API: /api/restore POST method reboots the ASA

CSCvi07242

ASA Rest API agent in multicontext mode may throw error: NOT_AVAILABLE_IN_SINGLE_CONTEXT

CSCvf43974

Rest-API queries return “Resource-not-found” for existing resources

CSCvf50673

ASA REST-API gives incomplete responses for extended ACL entries GET request

Resolved Bugs in 1.3(2)-221
Table 12. Resolved Bugs in 1.3(2)-221

Bug ID

Title

CSCvh12877

ASA REST-API shows NAT rule even though it was deleted from configuration

Open and Resolved Bugs in 1.3(2)-200

Open Bugs in 1.3(2)-200
Table 13. Open Bugs in 1.3(2)-200

Bug ID

Title

CSCvg18921

Not able to query REST API, Internal server error 500

CSCvf50673

ASA REST API gives incomplete responses for extended ACL entries GET request

CSCvb46271

REST API does not report an error while it fails to delete object-group

Resolved Bugs in 1.3(2)-200
Table 14. Resolved Bugs in 1.3(2)-200

Bug ID

Title

CSCvg17528

ASA REST API Agent failed, reason: OUTOFMEMORY_CONDITION_OCCURED

CSCvf87412

Unable to configure access-list with service-object having numeric name through REST API

CSCvd33185

Deleting network object deletes the NAT entry but REST API doesn't show deletion

CSCvd68137

After upgrading ASA from 9.5 to 9.6.2, compliance status is not readable via REST API

Open and Resolved Bugs in 1.3(2)-100

Open Bugs in 1.3(2)-100

None.

Resolved Bugs in 1.3(2)-100
Table 15. Resolved Bugs in 1.3(2)-100

Bug ID

Title

CSCvb21388

ASA REST API not working on trustpoint with both Identity and CA certs

Open and Resolved Bugs in 1.3(2)

Open Bugs in 1.3(2)
Table 16. Open Bugs in 1.3(2)

Bug ID

Title

CSCvb21388

ASA REST API not working on trustpoint with both Identity and CA certs

Resolved Bugs in 1.3(2)
Table 17. Resolved Bugs in 1.3(2)

Bug ID

Title

CSCut43581

ikev2globalparams - Maximum number of SAs out of range

CSCuy55989

/api/licensing/smart/asav/info returns 500 error on ASAv 9.5.2.200

CSCuz47825

Duplicate error message is not coming in response.

CSCva44402

ASA REST API: /cli api fail in System context by authentication fail.

CSCva50812

500 error when sending multiple requests to /api/cli?context=system

CSCva37834

REST-API does not create ACL remarks

Open and Resolved Bugs in 1.3(1)

Open Bugs in 1.3(1)
Table 18. Open Bugs in 1.3(1)

Bug ID

Title

CSCut43581

ikev2globalparams - Maximum number of SAs out of range

CSCuy55989

/api/licensing/smart/asav/info returns 500 error on ASAv 9.5.2.200

Resolved Bugs in 1.3(1)
Table 19. Resolved Bugs in 1.3(1)

Bug ID

Title

CSCuw76606

When bulk API fails, no error message is returned

CSCuw05856

/licensing/smart/asav: changing licenseServerUrl results in 500 error

CSCuy15807

Can’t setup multiple default routes on different interfaces with same metric

Related Documentation

For additional information on the ASA, see Navigating the Cisco ASA Series Documentation.