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/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 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. |
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://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:
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://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:
The top-level element in the response document, with the following attributes:
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: