 |
The Xentara Web Service v2.0
User Manual
|
|
The Xentara Web Service v2.0
User Manual
|
The Xentara web service can define one or more servers using different TCP/IP ports. This allows defining different servers for different audiences, e.g. one server for use by an HMI client, and one one for system maintenance. The different server can use different authentication schemes, and different server certificates.
Each Xentara web service server defines a number of endpoints. The paths of these endpoints can be arbitrary, but it is recommended that they contain an API version number. Many Web Services use endpoints that start with “/api/v1/”, for example. This allows retaining backwards compatibility with older clients, even if breaking changes need to be made to the endpoint names.
Each endpoint is connected to a Xentara data point. The endpoint will be read only, read/write, or write-only, depending on the readability and writability of the underlying data point.
The Xentara web service only accepts requests that contain a valid authentication. Every HTTP request addressed to the Xentara web service must contain an Authorization header containing a valid authorization, as described in section 4.2. of RFC 7235. Depending on the server configuration, the Xentara web service supports the “Bearer” and/or “Basic” authentication schemes.
If the Authorization header is missing, or if it does not provide any valid credentials, the Xentara web service will return a 401 Unauthorized response that includes a “WWW-Authenticate” header, as described in section 4.1. of RFC 7235.
If the Authorization is recognized, but the provided authorization does not have sufficient privileges to read or write the requested endpoint, the Xentara web service will return a 403 Forbidden response.
If the Authorization is malformed and cannot be decoded, then the Xentara web service will return a 400 Bad Request response.
If enabled in the server configuration, the Xentara web service supports OAuth 2.0 authorization using the HTTP “Bearer” authentication scheme. To authenticate a request using a bearer token, send a JSON Web Token along in the Authorization header using Bearer as the authentication scheme, as decribed in 2.1. Authorization Request Header Field of RFC 6750 — The OAuth 2.0 Authorization Framework: Bearer Token Usage. The required parameters for the token, like the correct issuer and audience, depend on the server configuration. Please contact the maintainer of the Xentara system you connecting to for the necessary details.
If enabled in the configuration, the Xentara web service supports username/password authorization using the HTTP “Basic” authentication scheme. To authenticate a request using a username and password, encode the credentials as described in section 2 of RFC 7617, and send them along in the Authorization header using Basic as the authentication scheme.
An endpoint in Xentara is read using HTTP GET requests. The body of the request is ignored.
If the data point was successfully read, the Xentara web service will reply with a 200 OK response containing the current value, the quality of the value. Depending on the server configuration, the response may also contain other attributes of the value.
The body of the response will be formatted as a JSON object in compact form. Each member of the Object contains the value of one attribute, where the member name is simply the name of the attribute. A response containing the value and quality of a data point might look as follows, for example:
{"value":12.7,"quality":"good"}
If an error occurs, the Xentara web service will reply with an error response containing one of the status codes registered in the Hypertext Transfer Protocol (HTTP) Status Code Registry at IANA. The body of the error response will usually contain an error message with content type “text/plain;charset=utf-8”.
If the endpoint exists, but is not readable, the Xentara web service will respond with 405 Method Not Allowed.
An endpoint in Xentara is read using HTTP POST requests. The body of the request must contain a JSON object with a single member named "value", that contains the value to be written. A request to write the value of a data point might look as follows, for example:
{"value":22.8}
The JSON object does not have to be formatted compactly, any valid JSON will be accepted. The body could also be sent like this:
{
"value": 22.8
}
The actual value can be a JSON number, a JSON string, or a JSON Boolean value (true or false). If the value cannot be converted to the data type of the corresponding data point, an error response is returned.
If the data point was successfully written, the Xentara web service will reply with 204 No Content.
If an error occurs, the Xentara web service will reply with an error response containing one of the status codes registered in the Hypertext Transfer Protocol (HTTP) Status Code Registry at IANA. The body of the error response will usually contain an error message with content type “text/plain;charset=utf-8”.
If the endpoint exists, but is not readable, the Xentara web service will respond with 405 Method Not Allowed. If the given value is not acceptable (type mismatch error, value out of range, etc.), the Xentara web service will respond with 422 Unprocessable Content. The status code 422 Unprocessable Content will also be returned if the body of the request does not contain a properly formatted JSON document.
The Xentara web service exposes URLs that allow you to read multiple endpoints in a single request. Each parent path in the endpoint hierarchy contains a special endpoints named “.batch-read”, that can be used to read multiple other endpoints under that path. The endpoint “/api/v1/turbine/.batch-read” can be used to read multiple endpoints whose paths begin with “/api/v1/turbine/” for example.
You can read multiple endpoints by sending send a POST request to the “.batch-read” endpoint. The body of the request must contain a JSON array containg the relative paths of the endpoints to read.
To read the endpoints “/api/v1/turbine/temperatures/intake” and “/api/v1/turbine/temperatures/exhaust” from the server xentara.local:8080, for example, you could send the following request to https://xentara.local:8080/api/v1/turbine/temperatures/.batch-read:
["intake","exhaust"]
Alternatively, you could send the following request to https://xentara.local:8080/api/v1/turbine/.batch-read:
["temperatures/intake","temperatures/exhaust"]
There is also “.batch-read” endpoint directly under the root URL. You could send the following request to https://xentara.local:8080/.batch-read:
["api/v1/turbine/temperatures/intake","api/v1/turbine/temperatures/exhaust"]
The JSON object does not have to be formatted compactly, any valid JSON will be accepted. The first request could also be sent like this:
[ "intake", "exhaust" ]
You can also read multiple endpoints by sending a GET request with appropriate HTTP Query parameters to a “.batch-read” endpoint. The query must consist of an underscore and an equal sign (“_=”), followed by a list of the relative paths of the endpoints to read, separated by plus signs (“+”).
To read the endpoints “/api/v1/turbine/temperatures/intake” and “/api/v1/turbine/temperatures/exhaust” from the server xentara.local:8080, for example, you could send a GET request to any of the the following URLs:
https://xentara.local:8080/api/v1/turbine/temperatures/.batch-read?_=intake+exhausthttps://xentara.local:8080/api/v1/turbine/.batch-read?_=temperatures/intake+temperatures/exhausthttps://xentara.local:8080/.batch-read?_=api/v1/turbine/temperatures/intake+api/v1/turbine/temperatures/exhaustIf an endpoint path contains a plus sign (“+”), it must be replaced by the equivalent percent encoding (“%2B”), to distinguish it from the list separator. Other characters not allowed in query strings (like “#” and “&”) must also be escaped, of course.
On success, the server will return a JSON array containing the data for each of the requested endpoints, in the same order as they are listed in the request. The response to a request to read the endpoints “/api/v1/turbine/temperatures/intake” and “/api/v1/turbine/temperatures/exhaust” (in that order) might look like this, for example:
[{"value":22.7,"quality":"good"},{"value":1314,"quality":"good"}]
The first array element will contain the value of the endpoint “/api/v1/turbine/temperatures/intake”, and the second array element will contain the value of “/api/v1/turbine/temperatures/exhaust”.
If an error occurs, the Xentara web service will reply with an error response containing one of the status codes registered in the Hypertext Transfer Protocol (HTTP) Status Code Registry at IANA. The body of the error response will usually contain an error message with content type “text/plain;charset=utf-8”.
If any of the specified endpoints do not exist, or are not readable, an error of 422 Bad Request (for POST requests) or 400 Bad Request (for GET requests with query parameters) will be returned, rather than 404 Not Found or 405 Method Not Allowed. The status codes 404 Not Found and 405 Method Not Allowed are only retuned if the “.batch-read” endpoint itself does not exist, or does not support the method.
The Xentara web service exposes URLs that allow you to write multiple endpoints in a single request. Each parent path in the endpoint hierarchy contains a special endpoints named “.batch-write”, that can be used to write multiple other endpoints under that path. The endpoint “/api/v1/climate-control/.batch-write” can be used to write multiple endpoints whose paths begin with “/api/v1/climate-control/” for example.
You can write multiple endpoints by sending send a POST request to the “.batch-write” endpoint. The body of the request must contain a JSON array listing the individial write operations to permorm. Each write operation is represented by a JSON object with two members: a member "endpont" that contains the relative path of the endpoint to write, and a member "value" that contains the value to be written.
To write the endpoints “/api/v1/climate-control/setpoints/temperature” and “/api/v1/climate-control/setpoints/humidity” on the server xentara.local:8080, for example, you could send the following request to https://xentara.local:8080/api/v1/climate-control/setpoints/.batch-write:
[{"endpoint":"temperature","value":22.5},{"endpoint":"humidity","value":55}]
Alternatively, you could send the following request to https://xentara.local:8080/api/v1/climate-control/.batch-write:
[{"endpoint":"setpoints/temperature","value":22.5},{"endpoint":"setpoints/humidity","value":55}]
There is also “.batch-write” endpoint directly under the root URL. You could send the following request to https://xentara.local:8080/.batch-write:
[{"endpoint":"api/v1/climate-control/setpoints/temperature","value":22.5},{"endpoint":"api/v1/climate-control/setpoints/humidity","value":55}]
The JSON object does not have to be formatted compactly, any valid JSON will be accepted. The first request could also be sent like this:
[
{
"endpoint": "temperature",
"value": 22.5
},
{
"endpoint": "humidity",
"value": 55
}
]
The Xentara web service will first validate the request, making sure it is a valid HTTP request, that it contains a valid authorization, that the body has the correct format etc. If the validation fails, it will reply with an error response containing one of the status codes registered in the Hypertext Transfer Protocol (HTTP) Status Code Registry at IANA. The body of the error response will usually contain an error message with content type “text/plain;charset=utf-8”.
If any of the specified endpoints do not exist, or are not writable, an error of 422 Unprocessable Content will be returned, rather than 404 Not Found or 405 Method Not Allowed. The status codes 404 Not Found and 405 Method Not Allowed are only retuned if the “.batch-write” endpoint itself does not exist, or does not support the method.
If all the requested write operations are valid and contain valid writable endpoints, the Xentara web service will execute the request. It will then report the result of the individual operations by returning a 200 Ok response. A 200 Ok response is sent regardless of whether the individual write operations succeeded or not. Write errors, including type mismatch errors, invalid values, out of range values etc. are reported in the body of the response, instead of as an HTTP status codes like 500 Server Error. This is necessary because and HTTP request can only contain a single response code, whereas each write operation will have a its own, separate error status. By sending a detailed error report in the body of the response, the individual results for the individual write operations can be reported separately.
The Xentara web service will return the results as a JSON array containing the status of each write operation, in the same order as they are listed in the request. Each of the status reports consists of a separate JSON object with a Boolean member named "success", denoting whether the operation succeeded or failed. If the operation failed, the status report with also contain a member "errorMessage" with a detailed error message explaining the cause of the failure.
The response to a fully successful request to write values to the endpoints “/api/v1/climate-control/setpoints/temperature” and “/api/v1/climate-control/setpoints/humidity” (in that order) will look like this, for example:
[{"success":true},{"success":true}]
The first array element represents the result of the write operation for endpoint “/api/v1/climate-control/setpoints/temperature”, and the second array element represents the result of the write operation for “/api/v1/climate-control/setpoints/humidity”.
If the first write operation succeeds, but the second one fails because the value is out of range, then the response will look like this:
[{"success":true},{"success":false,"errorMessage":"value is out of range"}]
If both operations fail, then the response will contain separate error codes for both write requests:
[{"success":false,"errorMessage":"interlock violated"},{"success":false,"errorMessage":"illegal value"}]
The Xentara web service also supports HTTP HEAD requests. A HEAD request is similar to a GET request, but returns no data. A HEAD request can be used to determine if an endpoint exists, and if it is readable using a GET request. It can also be used to check if a batch read GET request is valid.