Cisco Prime Infrastructure API
Prime Infrastructure API Documentation

# Structure

This page describes the request and response structure in a slightly more formal manner. The documentation for each request and response contains details of the specific attributes etc, and should be read in conjunction with this page.

## Requests

### URL Patterns

Basic data requests - these all support Filtering, Sorting and Paging.

URL Pattern | Request-Type | Function
--- | --- | ---
/api/v1/data | GET | Get all entity types. Note : This will show INTERNAL as well as external resources.
/api/v1/data/{eType} | GET | Get all instances of type {eType}, for example Devices.
/api/v1/data/{eType}/{id} | GET | Get a single instance identified by {id} of type {eType}.

"Service based" requests - these no NOT generally support Filtering, Sorting or Paging. The exact detail of the operation can be found in the detailed documentation.

URL Pattern | Request-Type | Function
--- | --- | ---
/api/op | GET | List all operations and their request types. Note : This will show INTERNAL as well as external operations.
/api/op/{sName} | Various | Depends on service {sName}.
/api/op/{sName}/{action} | Various | Depends on the semantics of the operation of the service {sName} and action {action}.

### Query Parameters

Query Parameter | Applicability | Meaning
--- | --- | ---
.json | /api/* | When present indicates that the response should be returned in json format.
.xml | /api/* | When present indicates that the response should be returned in xml format. This is the default in the absence of the .json parameter.
_docs | /api/* | Displays the documentation page.
.full | /api/v1/data/{eType} only | When 'true' indicates that whole objects be returned rather than just IDs of the entities.
.group | /api/v1/data/{eType} only | Filters the response based on content of the group specified by the string value, and the result of any applied operator.
.transform | GET/POST | Supplies the logical-name of a transform to be applied immediately before rendering to XML or JSON.
.maxResults | GET (where Paging supported) | The greatest number of results in terms of the heads of instance trees returned.
.firstResult | GET (where Paging supported) | The first result in terms of the heads of instance trees
.strict | /api/v1/data/{eType} only | When 'true', the property names used in queries are validated, and an error thrown if appropriate. (The default - ie when strict=false - is to ignore invalid property names with a simple log message).
.case_sensitve | /api/v1/data/{eType} only | When 'true', the string values used in filter queries are case sensitive. (The default - ie when .case_sensitive=false - is to treat comparisons as case insensitive).
_ctx.domain | GET | Sets the active domain to be that named in the query parameter value - this is, by default, "sticky" in the sense that once set, the active-domain remains set. The "stickiness" is not RESTful, and so it can be switched off in configuration.

### HTTP Headers

The following HTTP Headers are used to control the way in which data is returned to a client:

HTTP Header | Value | Meaning
--- | --- | ---
Accept | text/xml or application/json | May be used to control whether the data returned is formatted as XML or JSON
Accept-Language | For example: en-US | Specifies the language to be used in the response - this affects error messages that may be returned.
Content-Type | text/xml or application/json | Specifies the formatting of the data supplied to be either XML or JSON.
Accept-Encoding | gzip | Specifies that a compression (GZIP) may be applied to the data returned to the client.
Content-Encoding | gzip | Specifies that data supplied by the client with a request is compressed (GZIP).

## Responses

There are two response types, one for urls of the type /api/v1/data/* - a queryResponse and for /api/op/* -a mgmtResponse.

### Query Response Format

In the case of a successful request for entity data, (ie urls of the pattern /api/v1/data/* ) the data is returned in an 'envelope' that has this structure:

`<?xml version="1.0" encoding="utf-8"?> <queryResponse type="Devices" rootUrl="https://ncs-nbi-demo-1/webacs/api/v1/data" requestUrl="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices" responseType="listEntityIds"> ... </queryResponse>`

The structure consists of:

- /queryResponse - The top-level element in the response document, with the following attributes:
  - /queryResponse/@requestUrl - The full URL that was sent in the request. This will include Query Parameters etc.
  - /queryResponse/@rootUrl - The URL that identifies the root of all requests to the REST interface as currently deployed.
  - /queryResponse/@type Optional - The type of entity requested, where a request for a specific entity is requested.
  - /queryResponse/@id Optional -The ID of an entity, where a specific single entity was requested.
  - /queryResponse/@responseType - The response-type indicates the type of request made. It can assume one of these values:
    - listEntityTypes: The type of the entities requested (http://.../data).
    - listEntityIds: The IDs of all entities of a given requested type (http://.../data/<entity-type>).
    - listEntityInstances - content of all entities of a given type requested - http://.../data/<entity-type>?.full=true
    - getEntity: The content of a single requested entity (http://.../data/<entity-type>/<entity-id>).

Depending on the value of the queryResponse/@responseType attribute the elements that form the contents of the <queryResponse> will be as follows:

- (@responseType="listEntityTypes")

  /queryResponse/entityType

- (@responseType="listEntityIds")
  - /queryResponse/entityId* - Each element contains the type of an entity as text.
  - /queryResponse/entityId*/@type - The type of the actual entity returned, which is either the same as that returned as an attribute of the <queryResponse>, or that of a subclass.
- (@responseType="listEntityInstances")

  /queryResponse/entity* - Each element contains the structured data that describes an instance of an entity (see the next section).

- (@responseType="getEntity")
  - /queryResponse/entity - Each element contains the structured data that describes an instance of an entity.
  - /queryResponse/entity/@type - The type of the actual entity returned, which is either the same as that returned as an attribute of the <queryResponse>, or that of a subclass.
  - /queryResponse/entity/{any} - An element for which the name is:
    - A property that is a primitive. In this case, the value appears as text content.
    - A property that is a datatype. In this case, the value appears as one or more elements.

### Operation Invocation Response Format

In the case of a successful operation invocation, (ie urls of the pattern /api/op/* ) the data is returned in an 'envelope' that has this structure:

`<?xml version="1.0" encoding="utf-8"?> <mgmtResponse type="Devices" rootUrl="https://ncs-nbi-demo-1/webacs/api/op" requestUrl="https://ncs-nbi-demo-1/webacs/api/api/op/reportService/report" responseType="operation"> ... </mgmtResponse>`

The structure consists of:

- /mgmtResponse

  The top-level element in the response document, with the following attributes:

  - /mgmtResponse/@responseType - Currently the only valid response is 'operation' indicating an operation registered by an application.
  - /mgmtResponse/@rootUrl - The full URL that was sent in the request.
  - /mgmtResponse/@requestUrl - The URL that identifies the root of all requests to the REST interface as currently deployed.
  - /mgmtResponse/{any}* - The return-value of the operation which is a DTO of any type defined in the XMP-IM.

### Error Format

Errors that occur in the Prime Infrastructure API and in underlying components are reported in a canonical error document for which the format is as described in the following sections. An example of such a document, caused by an incorrectly formatted entity ID, is:

`<?xml version="1.0" encoding="UTF-8"?> <errorDocument> <httpResponseCode>401</httpResponseCode> <message>Incorrectly formatted ID supplied: 9.11.-PRS-107</message> <id>presentation.PRS-107</id> <uriPath>/data/Equipment/9.11</uriPath> <queryParams>'{}'</queryParams> </errorDocument>`

The document structure is as follows:

- /errorDocument - The envelope that contains the error data.
- /errorDocument/httpResponseCode - HTTP Response/Status Code as defined at: Error Codes and Responses
- /errorDocument/message - A user-friendly message carried by an exception.
- /errorDocument/exception? - This is returned only where a recognized XMP error message is not available, that is, for unexpected errors coming from lower-lying components, in which case the HTT Response Code will almost certainly be '500' ("Internal Server Error").
- /errorDocument/id? - The id of a Server error message.
- /errorDocument/uriPath - The path to the resource that gave rise to the error.
- /errorDocument/queryParams - The query-parameters that were passed as part of the URL.

- ← API Health
- Structure
- Sample Code →