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.
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/v1/op | GET | List all operations and their request types. Note : This will show INTERNAL as well as external operations. |
/api/v1/op/{sName} | Various | Depends on service {sName}. |
/api/v1/op/{sName}/{action} | Various | Depends on the semantics of the operation of the service {sName} and action {action}. |
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). |
.nocount | /api/v1/data/{eType} only | When 'true', the "count", "first", and "last" attributes are not included 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. |
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). |
There are two response types, one for urls of the type /api/v1/data/* - a queryResponse and for /api/op/* -a mgmtResponse.
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://my_server/webacs/api/v1/data" requestUrl="https://my_server/webacs/api/v1/data/Devices" responseType="listEntityIds"> ... </queryResponse>
The structure consists of:
Depending on the value of the queryResponse/@responseType attribute the elements that form the contents of the <queryResponse> will be as follows:
/queryResponse/entityType
/queryResponse/entity* - Each element contains the structured data that describes an instance of an entity (see the next section).
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://my_server/webacs/api/op" requestUrl="https://my_server/webacs/api/api/op/reportService/report" responseType="operation"> ... </mgmtResponse>
The structure consists of:
The top-level element in the response document, with the following attributes:
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>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: