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.
Basic data requests - these all support filtering, sorting and paging.
URL Pattern | Request-Type | Function |
---|---|---|
/api/v3/data | GET | Get all entity types. |
/api/v3/data/{eType} | GET | Get instances of type {eType}, for example Devices. Number of responses is subject to paging limits. |
/api/v3/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/v3/op | GET | List all operations and their request types. |
/api/v3/op/{sName} | Various | Depends on service {sName}. |
/api/v3/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 behavior in the absence of the .json parameter. |
_docs | /api/* | Displays the documentation page. |
.full | /api/v3/data/{eType} only | When 'true' indicates that whole objects be returned rather than just IDs of the entities. |
.group | /api/v3/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/v3/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/v3/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/v3/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. |
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. |
There are two response types, one for urls of the type /api/v3/data/* - a queryResponse and for /api/v3/op/* -a mgmtResponse.
In the case of a successful request for entity data, (ie urls of the pattern /api/v3/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/v3/data" requestUrl="https://my_server/webacs/api/v3/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/v3/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/v3/op" requestUrl="https://my_server/webacs/api/api/v3/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: