 |
The Xentara Web Service v1.2.1
User Manual
|
|
The Xentara Web Service v1.2.1
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 or a Xentara I/O point. The endpoint will be read only, read/write, or write-only, depending on the readability and writability of the underlying Xentara object.
The Xentara Wer Service only accepts requests that contain a valid authentication. To authenticate a request, 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.
If the Authorization is missing, or if it is incorrect, the Xentara Web Service will return a 401 Unauthorized response that includes a WWW-Authenticate header, as described in 3. The WWW-Authenticate Response Header Field of RFC 6750.
If the Authorization is recognized, but the token does not have sufficient access privileged to read or write an endpoint, the Xentara Web Service will return a 403 Forbidden response.
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 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 URL 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 requested endpoints do not exist, or is not readable, 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-read” endpoint itself does not exist, or does not support the method.
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.