Aurora Application Programming Interface (API)
Using API Filters
The API exists as an endpoint on the Aurora Server and enables the retrieval of live and historical data by filter or individual tag. A filter can be created in Aurora by grouping a set of tags together for retrieval through the API.
Each filter is limited to 40 tags. If you need a filter with more than 40 tags, please contact Support.
Setting Up a Filter
Open the Trending tab.
Select a Date-Time range.
Select a tag by clicking in the tag row. Once selected, Aurora On-prem will display the tag in the blank window.
All Available Tags by Date Range
Column headers have filter options so that the list of tags can be relevant to the need. For example, the user can filter by Site, System, Entity, and so on.
Repeat step 2 until you have selected all the desired tags for the API Filter.
Populating the Selection Window
Type a Filter Name in the Save Tag Selection field.
Click Save; The API Filter is now available for use.
Naming and Saving Tag Selection
API Filters must be setup on each individual server.
API Authentication
The API uses basic authentication consisting of a user name and password. It is suggested that a user is created in Aurora specifically for API use and granted access to all systems containing tags that will be retrieved through the API.
Setup a Header with Basic Authentication
Build a string of the form username:password.
Base64 encode the string.
Supply an “Authorization” header with content “Basic ” followed by the encoded string.
For example, a user name of “test” with a password of “test” would be test:test which is dGVzdDp0ZXN0 after encoding. The request header should contain “Authorization: Basic dGVzdDp0ZXN0”.
API Methods
API calls are defined and highlighted in the table in this section.
Method | V1 Route | V2 Route | Description |
|---|---|---|---|
GET | /v1/filters | /v2/filters | Gets Filters owned by authenticated user. Includes all associated tags and tag detail. |
GET | /v1/filters/{filterId}/Historical | /v2/filters/{filterId}/Historical | Gets historical data for tags associated with the provided filter. |
GET | /v1/filters/{filterId}/Live | /v2/filters/{filterId}/Live | Gets live data for tags associated with provided filter. |
GET | /v1/tags/{tagId}/Historical | /v2/tags/{tagId}/Historical | Gets historical data for provided tag. |
GET | /v1/tags/{tagId}/Live | /v2/tags/{tagId}/Live | Gets live data for the provided tag. |
POST | /v1/tags/{tagId}?value={tvalue} | /v2/tags/{tagId}?value={tvalue} | Attempts to update value for provided tag. |
POST | /v1/tags/Historical | /v2/tags/Historical | Allows insert of data to telemetry tables for Minute, QuarterHour, Hour, and Day for one or more existing tags. |
GET | /v1/alarms | /v2/alarms | Returns list of current alarms. |
GET | /v1/alarms/{alarmId} | /v2/alarms/{alarmId} | Returns current state for provided alarm. |
GET /filters
Description: Gets Filters owned by the authenticated user. Includes all associated tags and tag detail.
Parameters: None
Supported Types: application/json
Sample Request: GET ../API/v1/filters
Responses: A successful request will return a HTTP status code of 200 and a response containing a filters object. See the Error Codes and Responses section for a full list of HTTP status and error codes.
GET /filters/{filterId}/Historical
Description: Gets historical data for the tags associated with the provided filter.
Parameters: Refer to the table in this section.
Name | Located In | Description | Required |
|---|---|---|---|
FilterId | Path | id of filter containing list of tags to return. | Yes |
Interval | Query string | Interval of data to be returned. Valid values are “Minute”, “QuarterHour”, “Hour”, and “Day”. | Yes |
Start | Query string | Starting date/time range of data to retrieve. | Yes |
End | Query string | Ending date/time range of data to retrieve. | Yes |
DateRangeType | Query string | Identifies time zone to use when applying the Start and End date range. Valid values are “UTC” and “Site”. If not set, default is “Site”. | No |
Supported Types
application/json
text/csv
Sample Request
GET ../API/v1/filters/{filterId}/Historical?Interval=QuarterHour&DateRangeType=Site&Start=2016-07-26
01:00:00&End=2016-07-27 01:00:00
Responses: A successful request will return a HTTP status code of 200 and a response containing a historical data object. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.
GET /filters/{filterId}/Live
Description: Gets live data for the tags associated with the provided filter.
Parameters: Refer to the table in this section.
Name | Located In | Description | Required |
|---|---|---|---|
FilterId | Path | id of filter containing list of tags to return. | Yes |
Supported Types: application/json
Sample Request: GET ../API/v1/filters/{filterId}/Live
Responses: A successful request will return a HTTP status code of 200 and a response containing a live data object. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.
GET /tags/{tagId}/Historical
Description: Gets historical data for the provided tag.
Parameters: Refer to the table in this section.
Name | Located In | Description | Required |
|---|---|---|---|
TagId | Path | The id of the tag to return. | Yes |
Interval | Query string | Interval of data to be returned. Valid values are “Minute”, “QuarterHour”, “Hour”, and “Day”. | Yes |
Start | Query string | Start date/time of data to retrieve. | Yes |
End | Query string | End date/time range of data to retrieve. | Yes |
DateRangeType | Query string | Identifies the timezone to use when applying Start and End dates. Valid values are “UTC” and “Site”. If not set, default is “Site”. | No |
Supported Types
application/json
text/csv
Sample Request
GET ../API/v1/tags/{tagId}/Historical?Interval=QuarterHour&DateRangeType=Site&Start=2016-07-2601:00:00&End=2016-07-27 01:00:00
Responses: A successful request will return a HTTP status code of 200 and a response containing a historical data object. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.
GET /tags/{tagId}/Live
Description: Gets live data for the provided tag.
Parameters: Refer to the table in this section.
Name | Located In | Description | Required |
|---|---|---|---|
TagId | Path | id of tag to return. | Yes |
Supported Types: application/json
Sample Request: GET ../API/v1/tags/{tagId}/Live
Responses: A successful request will return a HTTP status code of 200 and a response containing a live data object. See the Error Codes and Responses topic for a full list of HTTP status codes and error codes.
POST /tags/{tagid}?value={value}
Description: Attempts to update value for the provided tag.
Parameters: Refer to the table in this section.
Name | Located In | Description | Required |
|---|---|---|---|
TagId | Path | The id of tag to write a value against. | Yes |
Value | Query string | Value to write. This must match the defined tag type. So if the tag is a discrete type, the value must be true or false, otherwise, numeric. NOTE: If there’s a configured range for the tag, the value must be within the range or an error will be returned. | Yes |
Supported Types: application/json
Sample Request: POST ../api/v1/tags/{tagid}?value={value}
Responses: A successful request will return a HTTP status code of 200. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.
Post /v1/tags/Historical
Description: Allows insert of data to our telemetry tables for Minute, QuarterHour, Hour and Day for one or more existing tags.
Parameters: None
Supported Types: application/json
Sample Request: POST ../api/v1/historical
Request Body: Accepts historical data object.
Responses: A successful request will return a HTTP status code of 200. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.
Get /v1/alarms
Description: Returns a list of current alarms.
Parameters: None
Supported Types: application/json
Sample Request: GET ../api/v1/alarms
Responses: A successful request will return a HTTP status code of 200 and a response containing an alarm data object. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.
Get /v1/alarms/{alarmid}
Description: Returns the current state for the provided alarm.
Parameters
Parameters: Refer to the table in this section.
Name | Located In | Description | Required |
|---|---|---|---|
Alarmid | Path | The id of the alarm to retrieve. | No; If not supplied, all current alarms will be returned. |
Supported Types: application/json
Sample Request: GET ../api/v1/alarms/{alarmid}
Responses: A successful request will return a HTTP status code of 200 and a response containing an alarm data object. See the Error Codes and Responses section for a full list of HTTP status codes and error codes.