1. Home
  2. OSS Drivers & Modules
  3. ossRestApiServer API Access Guide

ossRestApiServer API Access Guide

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.

Figure 1: API Interaction Overview

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 CodeResponseDescription
200OKThe request succeeded
400Bad RequestThe request was invalid
401UnauthorizedThe request authorisation was invalid,
the client may need to refresh the access token
Table 1: Request Responses

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

Token Request Response

The response returned by the token request is JSON data containing the three fields described in Table 2.

JSON Response FieldDescription
access_tokenThe token value to use for API access requests.
refresh_tokenThe token to use to refresh the access token when it expires.
expires_inThe number of milliseconds the access token is valid for.
Table 2: Token Request Response Fields

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 KeyValue Description
valueA string containing the point value.
statusA String containing a comma separated list of
status flag identifiers that apply to the point.
Table 3: Read Point Response Keys

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 NameDescription
slotPathThe point to write to.
valueThe value to write.
priorityThe slot to write to ( 1 to 16).
Table 4: Write Point Fields

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 IndexValue Description
timeThe time of the history record.
This time is specified as the number of milliseconds since the epoch.
(1-1-1970 00:00:00)
valueThe history record data value
statusA string containing a comma separated list of status flag
identifiers for the history record.
Table 5: Standard History Response Keys

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 FieldDescription
yyyyFour digit year
MMTwo digit month (01-12)
ddTwo digit day of month(01-31)
hhTwo digit hour, 24 hour clock (00-23)
mmTwo digit minute (00-59)
ssTwo digit second (00-59)
fffUp to 3 digit fraction of a second
Table 6: History Time Field Descriptions

For example:

…/query/history/Floor2/elecMeter?begin=2019-03-21T15:34:51.713Z&end=2019-03-23T20:45:11.371Z

Updated on June 11, 2024

Was this article helpful?

Related Articles

Existing Customer?
Need some technical support from the One Sight team?
CONTACT SUPPORT