Implementing the Generic (Rest) API

The Generic (Rest) API allows your organization to implement a bespoke REST API that will extract telemetry from your system. InfoWorks WS Pro and IWLive Pro are Clients of this REST API. Your IT department will provide the Server for the REST API.

Below are defined the API functions that InfoWorks WS Pro and IWLive Pro expect to find.

Your IT department is responsible for ensuring suitable security in the implementation of this REST API.

Base URL

Base_url will be of the form: https://MyTelemetry:Portnumber

Basic connection

Base_url / in the Live data adaptor, logon page this will show success for "Test connection"

List of tags

Base_url /tags will return a list of tags for the Tags drop down in the live data feeds page.

Request:

• Base_url/tags

Response:

• Success
  • {"tags": ["name"…]}
  • Example
    • {"tags": ["tag name 1","tag name 2","tag name 3","tag name 4"]}
• 500 {error: {message: error detail}}

Check that tag exists

Base_url/tags/tagname confirms that a particular tag name exists.

Request:

• Base_url/tags/tagname
• Parameters
  • limit=x (how many)
    • default 1000
  • offset=y (staring at)
    • default 0

Response

• 404 {"error": "Tag not found"}
• 500 {error: {message: error detail}}
• Success {"exists": true}

Return time varying data for a tag

Base_url/tags/tagname/history will return time varying data for a particular tag.

Request

• base_url/tags/tagname/history
  • Parameters
    • limit=x (how many)
      • default 1000
    • offset=y (starting at)
      • default 0
    • startdate=YYYY-MM-DDThh:mm:ssZ
    • enddate= YYYY-MM-DDThh:mm:ssZ
    • order=a (ASC | DESC)
      • default ASC

Response

• 404 {"error": "Tag not found"}
• 404 {"error": "History not found"}
• 500 {error: {message: error detail}}
• Success {"result": {"tagname": "aaa","values": [ {"timestamp":"ISO_datetime": "valueTypeName": value}…]}}
  • ISO datetime YYYY-MM-DDThh:mm:ss.mmmZ
  • ValueTypeName
    • doubleValue
    • integerValue
    • booleanValue
    • stringValue

Example responses

Example 1

{
"result": {"tagname":"tag name 2","values": [{"timestamp":"2023-09-01T23:00:00.000Z","integerValue": 0}]
}

Example 2

{
"result": {"tagname":"tag name 3","values": [{"timestamp":"2023-09-01T23:00:00.000Z","booleanValue": false}]
}

Example 3

{
"result": {"tagname":"tag name 4","values": [{"timestamp":"2023-09-01T23:00:00.000Z","stringValue": "ABC2460189.5"}]
}

Example 4

{
 	"result": {
		"tagname": "tag name 15",
		"values": [
			{
				"timestamp": "2024-03-15T09:40:00.000Z",
				"doubleValue": -0.9659258262890684
			},
			{
				"timestamp": "2024-03-15T09:45:00.000Z",
				"doubleValue": -0.9612616959383188
			}
		]
}
}