Updated for version 1.0.0
Introduction
The One Sightsolutions module ossRestApiServer software provides a way for third party applications to read and write point data, and read history data via HTTP API requests to a Niagara station. It provides an implementation of OAuth 2.0 token authentication to make this data transfer secure.
** This guide describes how to access the API from an external computer. There is a separate document that describes how to install and configure the software in Niagara here.
Requirements
It is assumed that the reader is familiar with the use of web APIs.
The ossRestApiServer software must have been installed on a Niagara host and a client application must have been created.
You must read the End User License Agreement before using this software.
Overview of Api Operation
A simple overview of the API interaction is shown in Figure 1.
For each API client the ossRestApiServer will generate a set of client credentials.
These pieces of information are transferred to the client application manually (e.g. cut and paste).
The client application will then use those credentials when making a token request to the API, the ossRestApiServer software will then generate an access token and a refresh token and send them back to the client.
The client may then request data from the API using the access token for authorisation.
The access token is only valid for a limited period of time, when this time expires the client may use the refresh token to obtain a new access token and then continue making data requests using the new access token.
Most installations will only allow the client application credentials to be used once to generate the access tokens. Then only the tokens can be used and must be refreshed when they expire.
Client Access Credentials
The ossRestApiServer software implements the OAuth Client Credentials grant.
To access the API you will need the client credentials for the application you will be using.
These values will have been created by the person who set up the ossRestApiServer application on the Niagara host you will be connecting to.
The client credentials consist of a client identifier and a client secret which are both alphanumeric values which can be cut and pasted into emails and documents.
Client credentials should be kept secret and transferred from the ossRestApiServer application to the client accessing the API in a secure manner.
Note that the client identifier and client secret are each single line values. Any line breaks in these values should be removed. Care should be taken if these values are transferred between non-windows systems as line break characters can differ between these systems and values can get corrupted. Contact the person who set up the ossRestApiServer application if you receive client credential values that do not consist of single line values and are unsure how to reformat them.
Request Overview
General Request Information
Information is read and written to the ossRestApiServer API using HTTP requests.
All HTTP requests to the API must use the secure extension HTTPS (i.e. the URL should start with ‘https://’ scheme), so any client must be capable of supporting HTTPS. The person who set up the ossRestApiServer application should be able to tell you the hostname or IP address of the host and the port number to use for the HTTPS requests.
Note that the port number will often not be specified if the default HTTPS port number of 443 is being used. All request types use a URL of the format:
https://<hostname>[:<port-number]/ossRestApiServer/<requestPath>
The HTTP authorisation headers of each request must be assigned correctly for the access to succeed, as described in the following sections for each type of request.
Request Responses
Most API requests will result in one of three responses as described in Table 1.
| HTTP Status Code | Response | Description |
| 200 | OK | The request succeeded |
| 400 | Bad Request | The request was invalid |
| 401 | Unauthorized | The request authorisation was invalid, the client may need to refresh the access token |
By default request failure responses will only return basic fault information, for security reasons.
The ossRestApiServer software can be configured in Niagara to return more informative debug information in API failure responses. This can be useful during initial development of systems integrating with the API. It is recommended that this debug information is disabled when it is no longer required.
Authorization Requests
Authorisation requests are used to obtain and update the access token required for API data requests.
Token Request
Token Request URL
Requests to obtain access tokens from the API use the HTTP POST request method. The token request URL has the format:
https://<hostname>/ossRestApiServer/token
Specific HTTP headers must also be included in the token request as well as body data, which are described in the following sections.
Authorization Header
The authorisation header for the token request must contain the client identifier (as user name) and
client secret (as password) base64 encoded according to the Basic Access Authentication (BA)
mechanism (as defined in RFC 7617).
This involves creating a raw credentials text value in the following format:
<client-identifier>:<client-secret>
This is the client identifier text followed by a colon character (:) followed by the client secret text.
This raw credentials value is then base64 encoded to create the encoded credentials.
The encoded credentials are then included in the HTTP header in the basic authorisation field as follows:
Authorization: Basic <encoded-credentials>
Content Type Header
The content type header for the token request must be as follows:
Content-Type: application/x-www-form-urlencoded
Request Body
As the token request uses the HTTP POST method it must contain data in the body in the following format:
grant_type=client_credentials&scope=<access-scope>
Where access-scope is one of the following according to what type of access the client requires:
• read
• read write
Note the space between the words read and write in the second option.
Token Request Response
The response returned by the token request is JSON data containing the three fields described in Table 2.
| JSON Response Field | Description |
| access_token | The token value to use for API access requests. |
| refresh_token | The token to use to refresh the access token when it expires. |
| expires_in | The number of milliseconds the access token is valid for. |
The following is an example response:
{
“access_token”:”780bd378e051391e8728819826ac3f7d”,
“refresh_token”:”5c221b522cd970230b08c515bccd3391″,
“expires_in”:3600000
}
Token Refresh Request
Token Refresh Request URL
Requests to refresh the access token use the HTTP POST request method.
The token request URL has the format:
https://<hostname>/ossRestApiServer/token/renew
Specific HTTP headers must also be included in the token request as well as body data, which are described in the following sections.
Authorization Header
The authorisation header for the token refresh request must contain the refresh token (from the previous token request) as a bearer token.
Therefore, the authorisation field should be as follows:
Authorization: Bearer <refresh-token>
Request Body
The token refresh request uses the same body data and content type header as the original token request, as described in ‘Token Request – Content Type Header’ and ‘Token Request – Request Body’.
Token Request Response
The response returned by the token refresh request is the same as that returned for the initial token request, as described in ‘Token Request – Token Request Response’.
Data Requests
Data Request Methods
All data read requests use the HTTP GET method and all data write requests use the HTTP PUT method.
Data Request URL
All data requests use a URL of the following format:
https://<hostname>/ossRestApiServer/query/<resource-path>
The resource path required for each request type is described in the following sections.
Authorization Header
All data requests require a HTTP authorisation header field that contains a valid access token in the following format:
Authorization: Bearer <access-token>
Data Request Responses
All valid request responses return JSON data.
The JSON data may contain an array or a single JSON object depending on the type of request.
Access Rights
Note that access to both point and history resources are controlled by licensing and a user access rights system in Niagara.
Therefore, the request may fail if the Niagara station or the ossRestApiServer software is not configured correctly to access the specified resource.
Point Data Read Requests
List Points
This request will return a list of all accessible points on the Niagara host.
List Points Request URL
https://<hostname>/ossRestApiServer/query/listPoints
List Points Response Data Format
The request returns a JSON array of strings which contain the point slot path values.
For example:
[
“/Folder1/BooleanTestPoint”,
“/Folder1/NumericTestPoint”,
“/Folder2/enum_point”
]
Reading Point Data
This request will return the value of a single point.
Point Read Request URL
https://<hostname>/ossRestApiServer/query/readPoint/<slotPath>
Point Read Response Data Format
The request returns a single JSON object which contains the point value and status using the keys and values described in Table 3.
| JSON Key | Value Description |
| value | A string containing the point value. |
| status | A String containing a comma separated list of status flag identifiers that apply to the point. |
Refer to the Niagara documentation for a list of the status flag identifier values and their meaning. For example:
{
“value”:”70.00″,
“status”:”ok”
}
Point Data Write Requests
Write Point Method
Requests to write data to the API use the HTTP PUT method.
Write Point Slots
Points in Niagara have a list of priority slots with values 1 to 16.
When writing to a point the client must specify which point slot is to be written to.
Please read the Niagara documentation or contact the ossRestApiServer administrator for more information regarding what slot to select for writing.
Write Point URL
The URL to use to write to a slot has the following format:
https://<hostname>/ossRestApiServer/query/writePoint/<write-spec>
Where the <write-spec> has the following structure:
<slotPath>?value=<value>&priority=<priority>
The write-spec parameters are described in Table 4.
| Field Name | Description |
| slotPath | The point to write to. |
| value | The value to write. |
| priority | The slot to write to ( 1 to 16). |
For Example
…/query/writePoint/Heating/setpoint?value=22.3&priority=5
Write Point Type
The API write request supports writing to Boolean, Numeric, Enum or String point types.
You will receive a bad request (400) error response if you attempt to write an invalid type value to a point.
Boolean point values should be specified using the values ‘true’ or ‘false’.
Enum point values should be specified using a numeric integer ordinal value.
History Data Read Requests
List Histories
This request will return a list of all accessible histories on the Niagara host.
List Histories Request URL
https://<hostname>/ossRestApiServer/query/listHistories
List Histories Response Data Format
The request returns a JSON array of strings which contain the history identifier values.
Note that the history identifier value will always start with the name of the Niagara station.
For example:
[
“/TestStation/officeTemp”,
“/TestStation/officeCo2”,
“/TestStation/elecMeter”
]
Reading History Data
This request will return an array of history record values.
History Request URL
https://<hostname>/ossRestApiServer/query/history/<history-id>
Where the ‘history-id’ field is of the form shown in the list of histories (i.e. starting with the station name).
History Response Data Format
The request returns a JSON array of arrays, where each secondary array represent a history record.
Each history record array contains three strings as described in Table 5.
| Array Index | Value Description |
| time | The time of the history record. This time is specified as the number of milliseconds since the epoch. (1-1-1970 00:00:00) |
| value | The history record data value |
| status | A string containing a comma separated list of status flag identifiers for the history record. |
Refer to the Niagara documentation for a list of the status flag identifier values and their meaning.
For example:
[
[“1564389180012″,”40.04″,”ok”],
[“1564389240015″,”0.0″,”fault”],
[“1564389300019″,”155.82″,”ok”],
[“1564389360026″,”128.38″,”ok”]
]
History Time Range
History requests support specifying a time period, either using a keyword or by specifying the absolute begin and/or end times.
A time period is specified by adding parameters to the end of the URL.
History Time Range Keyword
A history time period may be specified by using the ‘range’ parameter to define the time range keyword.
The valid time range keywords are shown in the following list:
• TODAY
• YESTERDAY
• WEEKTODATE
• LASTWEEK
• LAST7DAYS
• MONTHTODATE
• LASTMONTH
• YEARTODATE
• LASTYEAR
For example:
…/ossRestApiServer/query/history/Station/officeTemp?range=YESTERDAY
History Time Range Absolute Begin/End
A history time period may be specified by defining the absolute begin and/or end times for the data required.
The begin time can be specified using the ‘begin’ parameter.
The end time can be specified using the ‘end’ parameter.
Both time parameters must use the following (ISO 8601) format:
yyyy-MM-ddThh:mm:ss.fff
Note that the ‘T’ character appears literally as shown, but the other fields should be given numeric values as described in Table 6.
| Time Field | Description |
| yyyy | Four digit year |
| MM | Two digit month (01-12) |
| dd | Two digit day of month(01-31) |
| hh | Two digit hour, 24 hour clock (00-23) |
| mm | Two digit minute (00-59) |
| ss | Two digit second (00-59) |
| fff | Up to 3 digit fraction of a second |
For example:
…/query/history/Floor2/elecMeter?begin=2019-03-21T15:34:51.713Z&end=2019-03-23T20:45:11.371Z