Cisco Network Assurance Engine REST API User Guide
The Cisco Network Assurance Engine REST API
IMPORTANT: This document describes the features, operation, and syntax of the Cisco Network Assurance Engine (NAE) REST API as of the current release when written. The features, operation, and syntax of the API are subject to change in future releases, and Cisco cannot guarantee backwards compatibility with prior releases.
Overview
The Cisco Network Assurance Engine (NAE) REST API provides an alternative operation method to the Cisco NAE GUI. The REST API gives programmatic access to all assurance models in addition to providing fully automatable management of the Cisco NAE.
The REST API is a set of programming interfaces that uses Representational State Transfer (REST) architecture. The API contains resources represented by Uniform Resource Identifiers (URIs), which allow you to unambiguously identify each resource. Each URI contains a protocol used to exchange the messages and the resource location string. A URI can refer to a single object or a collection of objects.
A REST API operation is executed by sending an HTTP GET, POST, PUT, or DELETE
request in the format of /nae/api/v1/{resource} to a URI within
the Cisco NAE. The HTTP request typically includes a payload message
in JavaScript Object Notation (JSON) format, and the HTTP response typically
includes a JSON format message body. In some cases, the HTTP request may also
contain URL parameters.
- A GET request may submit URL parameters and returns a JSON data structure containing the requested data or status. The GET method is nullipotent, meaning that it can be called zero or more times without making any changes; in other words, it is a read-only operation.
- A POST request typically creates a new object, such as a user or fabric. It should be sent only once for each object created. A POST request submits a JSON data structure to the specified resource and returns a JSON data structure containing confirmation or failure information.
- A PUT request is used to modify an attribute of an existing object. A PUT request submits a JSON data structure to the specified resource and returns a JSON data structure containing confirmation or failure information. It is not necessary for the payload structure of a PUT request to contain the attributes that are not being modified. The PUT method is idempotent, meaning that there is no additional effect when a request is sent more than once with the same input parameters.
- A DELETE request may submit URL parameters and returns a JSON data structure containing confirmation or failure information. The DELETE method is idempotent, meaning that there is no additional effect when a request is sent more than once with the same input parameters.
You can use common developer tools such as cURL, Postman, or a programming language to compose and send the HTTP request and the JSON payload.
An expansion of this guide, including examples, workflows, and status/error codes, can be found on the Cisco Network Assurance Engine documentation page.
For OpenAPI (formerly Swagger) format documentation of NAE REST API commands, see About The REST API Reference (OpenAPI/Swagger).