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.

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/%7Emcrawfor/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.