
Cisco Evolved Programmable Network Manager API
Evolved Programmable Network Manager 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 parameters 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/v4/data | GET | Get all entity types.
/api/v4/data/{eType} | GET | Get instances of type {eType}, for example Devices. Number of responses is subject to paging limits.
/api/v4/data/{eType}/{id} | GET | Get a single instance identified by {id} of type {eType}.

"Service based" requests - these do 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/v4/op | GET | List all operations and their request types.
/api/v4/op/{sName} | Various | Depends on service {sName}.
/api/v4/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 behavior in the absence of the .json parameter.
_docs | /api/* | Displays the documentation page.
.full | /api/v4/data/{eType} only | When 'true' indicates that whole objects be returned rather than just IDs of the entities.
.group | /api/v4/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 maximum number of results to return.
.firstResult | GET (where paging supported) | The first result, or offset into the data, to return.
.strict | /api/v4/data/{eType} only | When 'true', the property names used in queries are validated, and an error will be thrown if appropriate. When 'false', invalid property names are ignored. Since API version 3 the default value is 'true'. For earlier versions the default value is 'false'.
.case_sensitve | /api/v4/data/{eType} only | When 'true', the string values used in filter queries are case sensitive. (The default behavior is to treat comparisons as case insensitive.)
.nocount | /api/v4/data/{eType} only | When 'true', the "count", "first", and "last" attributes are not included in the response. Getting the values of these attributes requires additional time, therefore setting this to 'true' will improve performance. Defaults to 'false'.
_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 may affect error messages that may be returned.
Content-Type | text/xml or application/json | Specifies the formatting of the request payload to be either XML or JSON.
Accept-Encoding | gzip | Specifies that compressed data may be returned to the client.
Content-Encoding | gzip | Specifies that data supplied by the client with a request is compressed.

## Responses

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

### Query Response Format

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

    <?xml version="1.0" encoding="utf-8"?>
    <queryResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/data"
        requestUrl="https://my_server/webacs/api/v4/data/Devices" responseType="listEntityIds" domain="domainName">
    ...
    </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>).
  - /queryResponse/@domain - The virtual domain name which was active to the request. This attribute is available since API version 4.

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/v4/op/* ) the data is returned in an 'envelope' that has this structure:

    <?xml version="1.0" encoding="utf-8"?>
    <mgmtResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/op"
        requestUrl="https://my_server/webacs/api/api/v4/op/reportService/report" responseType="operation" domain="domainName">
    ...
    </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/@domain - The virtual domain name which was active to the request. This attribute is available since API version 4.
  - /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 Evolved Programmable Network Manager 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>400</httpResponseCode>
        <message>Incorrectly formatted ID supplied: 9.11.-PRS-107</message>
        <id>presentation.PRS-107</id>
        <uriPath>/data/Equipment/9.11</uriPath>
        <queryParams>'{}'</queryParams>
        <domain>domainName</domain>
    </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 HTTP 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.
- /errorDocument/domain - The virtual domain name which was active to the request. This element is available since API version 4.

- API Health
- Structure
- Home