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

In previous chapter we configured ASA to support REST API interface and executed simply query. It was nice to see something in action but let’s now think how it’s working and how we can use it.

Every operation you can do using REST API you can also execute via traditional CLI commands or simplifying your life a little by using ASDM. Many of parameters you can fetch using SNMP or from syslog. So is it just another way to manage your device? Answer is both yes and no. Yes, because it is way of managing the device. No, because using REST API you have to stop thinking that you configure service but you are programming it usually as a part of bigger script or application.

REST API on ASA

REST API on ASA side is small plugin loaded into device flash memory and then activated using CLI.

 

As you can see several components are included in REST API architecture:

• REST Client is any external application that will be calling API methods
• REST Agent is this small piece of additional software installed on ASA is responsible of processing requests and communication with other ASA subsystems
• Web Server is used to handle HTTP communication that is used as transport protocol
• REST Daemon is responsible for handling debug and syslog messages
• LINA is core process which controls all Cisco ASA Software operations

To better understand relationship of those components let’s look what happen if we execute method as in previous chapter where we fetched information about firmware version using REST API.

1. REST Client establishes HTTPS communication with ASA Web Server
2. REST Client sends API request with authentication header
3. Web Server opens internal connection to REST Agent, forwards the HTTP request and wait for response
4. REST Agent process API request, analyze user and session related information that are included in request, then invokes CLI commands specific to the request via LINA
5. LINA process executes commands and gather results and sends is back to REST Agent
6. REST Agent prepares the response and sends it to Web Server
7. Web Server forwards the response to REST Client

As you can see there is strict logical separation of features performed by each component. In example Web Server never do any operations on response prepared by REST Agent before sending it to REST Client, it’s just responsible of handling the communication.

 

REST API Client

What can use REST API interface to perform all available operations? Pretty much every program or script that can use HTTP as transport protocol can be used. RESTClient or other web browser plugins are useful for testing purposes but not really handy in programming world for which API was created for.The whole beauty of REST API is that you can use programming languages or other tools to create scripts/programs that will be used in deployment or operating providing us automation. It also can be used by our own applications for automation.

It’s not uncommon that enterprises use multiple kind of “trusted sources” to store critical information. This information may be in example list of IP addresses allowed to access specific resources. Thanks to REST API programmers are able to embed code in centrally managed application that will perform ACL update based on information stored in “trusted source”. If you think more you’ll easily find scenarios where you can automate some tasks.

Most popular ways to use REST API are programming and scripting languages. Because REST and JSON are widely used standards proper modules are available

Python

Python is standard part of Linux system. json and urllib modules must be imported to Python script

Perl

Perl is also standard part of Linux and contains many useful libraries that can be used for data parsing or any other operation you may imagine. It also require some libraries to be installed

$ sudo perl -MCPAN e shell
cpan> install Bundle::CPAN
cpan> install REST:: Client
cpan> install MIME::Base64
cpan> install JSON

JavaScript

Web-based application will probably use JavaScript for communication with REST API.If you want to execute JavaScript from console installation of node.js is required

 JSON

All operations requires common and well defined structure for exchanging data. REST API uses JSON (JavaScript Object Notation) which is defined in RFC 4627. JSON is predefined MIME type identified by application/json. JSON standard base on two structures:

• A collection of name/value pairs
• An ordered list of values

Those are universal structures supported by all modern programming languages. Let’s look again at output we generated in previous chapter

 

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. }

Each object is defined within the braces. Objects can be embedded which creates hierarchical structure quite easy to read and process. Each value is represented as a pair separated by colon. First part is string representing the name of the value, the second is value itself.

Note that if you compare this format to SNMP Walk result names of the values are the OIDs followed by values themselves.

JSON standard defines few data types:

• Number
• String
• Array
• Boolean
• Object
• Null

We will get familiar with those data types later when we’ll be using them in practice.

Methods

REST API is used to perform operations on firewall. Parameters and responses are embedded using JSON structure. The methods we can use are:

• GET – retrieves data from specified object
• POST – creates the object with the supplied information
• PUT – adds the information to specific object
• DELETE – removes specific object
• PATCH – applies partial modification to the object

REST Request

In last chapter we executed GET method on specific resource using URL

https://172.16.1.64/api/controller/restconf/config/opendaylight-inventory:nodes/

First part, marked blue, is server identification while second part marked green is resource identification.

REST Response

Because HTTP is used as transport protocol first part of the response will be HTTPS status or error code.

If operation is performed successfully we will see one of following codes

• 200 Success OK – when executing GET method
• 201 Create – when execution POST method
• 204 No Content – when executing PUT, PATCH or DELETE methods

In case of errors following codes are expected

• 400 Bad Request – in situation when parameter is missing, incomplete or invalid
• 404 Not Found – when we try to call resource that is not available
• 405 Method Not Allowed – not all methods can be performed on all resources
• 500 Internal Server Error – return response may include an error object containing more details about the error