Network Assurance Engine

Standardized Query Responses

In response to any API command or query, the Cisco NAE REST API server returns an HTTP status code that indicates whether the request was successful, along with other information related to the request. The HTTP status codes are listed in the expanded reference documentation.

Any Cisco NAE REST API call that returns a response payload will return a JSON structure in the common response format. To aid with programmability and understanding, all responses follow a standard response structure, as described in Common Response Structure.

Common Response Structure

The Cisco NAE REST API common response JSON structure includes the fields described in the Common Response Field Definitions table. For an example of the JSON structure, see the Common Response Structure Example.

Common Response Field Definitions

Name Purpose
success Indicates whether the request was successful.
messages Displays messages, if any, associated with a request. A single request can return multiple messages, such as when multiple validation errors exist in a submitted form. Each message is composed of three attributes: a severity level (INFO, WARNING, or ERROR), a Cisco NAE-specific error code to assist technical support, and a user-friendly message string. Note that a message may be generated even when a request is successful. For example, a WARNING message is generated if the requested page size exceeds the allowed value. Some common error codes are listed in the expanded reference documentation.
value This object holds the actual results of the request as shown in the Response Payload Structure table.

Response Payload Structure

Name Purpose
namespaces Namespace declarations to prevent collisions between property names returned in the API response.
data_summary Summary information about the data returned in the response. The data summary object is composed of the following attributes:

  • total_count: Total number of records matched by this request. If the total count exceeds the page_size, multiple pages of data are returned. The links attribute contains the paging links for navigating between pages.

  • has_more_data: Boolean indicating whether there are additional data rows available in the response.

  • page_size: Maximum number of records returned by a single request. This attribute is user configurable using the $page query parameter (see Request Query Parameters) up to the maximum limit imposed by the system (currently 200 records).

  • current_page_number: Page number of this response data. Page numbers start at 0 and can be specified using the $page query parameter.

  • total_page_count: Total number of pages contained in the response. This value equals the (total_count/page_size) + 1

  • sort_fields: Array of one or more fields that specify the sorting criteria used in the response.

  • links: HATEOAS paging links for navigating between response pages.

Name Purpose
data The actual data object containing the returned records. This object is documented separately for each API. The data attribute is a mixed object returning a JSON object when only a single row is returned and an array of objects when multiple rows are returned. The self link for this request is contained in the data_summary.links section.

Query Response Pagination

Because the results of a query may consist of a large number of data records, the query response is typically paginated. A single page of data, page 0, is returned in the response structure of an initial query. When the results of the query exceed the size of a single page, additional pages can be requested either by specifying an explicit page number ($page in the query parameters or by using pagination links in the response structure of the initial query and subsequent queries.

The number of records per page ($size) can be specified as a query parameter.

The response structure of any multi-page query contains full query URLs that can be sent in subsequent GET operations to fetch the first, last, next, and previous pages of data results.

The Cisco NAE REST API uses the Hypermedia As The Engine Of Application State (HATEOAS) principle to present links to paginated resources in the ATOM format. Including these links in the response relieves the user from the task of composing them.

The following table lists the links that are present for each resource. These pagination links are found in the value.data_summary.links section of the response.

Relation Description
first Link to the first page of the result set
prev Previous page from the current page (not supplied for page 0)
next Next page from the current page (not supplied for the last page)
last Link to the last page of the result set
self URL pointing to the resource itself
Next