REST API Reference
Introduction
The WebAPI REST interface exposes several REST endpoints that allow access to different types of FrameWorX Server data. Endpoints can be accessed both via HTTP GET or HTTP POST, where POST usually allows submitting more than one request at the time, thus increasing efficiency. The sections on this page describe all available WebAPI REST endpoints.
The WebAPI REST interface needs some specific settings to function. Make sure your system is configured as described in Setting Up WebAPI REST before attempting to use these endpoints.
Reading Real-time Values (HTTP GET)
Reading Real-time Values (HTTP POST)
Writing Real-time Values (HTTP POST)
Reading Raw Historical Data (HTTP GET)
Reading Aggregated Historical Data (HTTP GET)
Reading real-time values (HTTP GET)
The Data endpoint accepts the name of the point to read as a query string parameter:
GET https://<host name>/fwxapi/rest/data?PointName=svrsim:sine double med -100 100
The response is a single-value array containing a JSON object carrying the name, value, timestamp and quality of the requested point:
{
"pointName":"svrsim:sine double med -100 100",
"value":96.27276317599106,
"timestamp":"2020-04-02T15:37:08.9924319Z",
"quality":0
}
Reading real-time values (HTTP POST)
For increased efficiency, it is possible to request multiple points at the same time from the Data endpoint when using HTTP POST. The POST body must contain a JSON object with a single property called PointName, which carries an array of point names:
POST https://<host name>/fwxapi/rest/data
Content-Type: application/json
{
"PointName": [ "svrsim:sine double med -100 100", "svrsim:ramp double med -100 100" ]
}
The response is an array containing a JSON object for each point requested, each object carrying the name, value, timestamp and quality of the requested point:
[
{
"pointName":"svrsim:sine double med -100 100",
"value":-89.40948359583616,
"timestamp":"2020-04-02T15:41:45.4938895Z",
"quality":0
},
{
"pointName":"svrsim:ramp double med -100 100",
"value":35.2179999999702,
"timestamp": "2020-04-02T15:41:45.4938895Z",
"quality": 0
}
]
Writing real-time values (HTTP POST)
One or more points can be written to using the Data/Write endpoint via HTTP POST. The POST body must contain a JSON array of objects containing the name of the point and the value to write:
POST https://<host name>/fwxapi/rest/data/write
Content-Type: application/json
[
{ "PointName": "svrsim:out int32", "Value": 42 },
{ "PointName": "svrsim:out double", "Value": 42.0 }
]
The response is an array containing a JSON object for each write operation, each object carrying the point name, whether the write succeeded and an error message in the case the write failed:
[
{
"pointName":"svrsim:out int32",
"success":true,
"errorMessage":"Good"
},
{
"pointName":"svrsim:out double",
"success":true,
"errorMessage":"Good"
}
]
Reading datasets (HTTP GET)
This endpoint allows to read dataset points, like the ones exposed by GridWorX. The Dataset endpoint accepts the name of the point to read as a query string parameter. If the dataset point itself has parameters, the parameter values can be included in the point name:
GET https://<host name>/fwxapi/rest/dataset?PointName=db:Northwind.OrdersByCustomerID<@CustomerID=ALFKI>
The response is an array of JSON objects, the objects have properties with the same name and equivalent data type as the columns of the dataset:
[
{
"OrderID":10643,
"CustomerID":"ALFKI",
"EmployeeID":6,
"OrderDate":"1997-08-25T00:00:00",
"RequiredDate":"1997-09-22T00:00:00",
"ShippedDate":"1997-09-02T00:00:00",
"ShipVia":1,
"Freight":29.4600,
"ShipName":"Alfreds Futterkiste",
"ShipAddress":"Obere Str. 57",
"ShipCity":"Berlin",
"ShipRegion":null,
"ShipPostalCode":"12209",
"ShipCountry":"Germany"
},
{
"OrderID":10692,
"CustomerID":"ALFKI",
"EmployeeID":4,
"OrderDate":"1997-10-03T00:00:00",
"RequiredDate":"1997-10-31T00:00:00",
"ShippedDate": "1997-10-13T00:00:00",
"ShipVia":2,
"Freight":61.0200,
"ShipName":"Alfred's Futterkiste",
"ShipAddress":"Obere Str. 57",
"ShipCity":"Berlin",
"ShipRegion":null,
"ShipPostalCode":"12209",
"ShipCountry":"Germany"
},
…
{
"OrderID":11011,
"CustomerID":"ALFKI",
"EmployeeID":3,
"OrderDate":"1998-04-09T00:00:00",
"RequiredDate":"1998-05-07T00:00:00",
"ShippedDate":"1998-04-13T00:00:00",
"ShipVia":1,
"Freight":1.2100,
"ShipName":"Alfred's Futterkiste",
"ShipAddress":"Obere Str. 57",
"ShipCity":"Berlin",
"ShipRegion":null,
"ShipPostalCode":"12209",
"ShipCountry":"Germany"
}
]
Reading raw historical data (HTTP GET)
This endpoint allows to read historical data, for example data that has been logged in Hyper Historian.
The History endpoint accepts the point name, start time and end time as query string parameters:
GET https://<host name>/fwxapi/rest/history?PointName=hh:\Configuration\Signals:SineFast&StartDate=2020-03-04T11:25:00-0400&EndDate=2020-04-02T11:27:00-0400
The response is an array of JSON objects, each object representing a sample carrying the name, value, timestamp and quality of the requested point:
[
{
"pointName": "hh:\\Configuration\\Signals:SineFast",
"value": null,
"timestamp": "2020-03-04T08:37:30.98Z",
"quality": 2147483696
},
{
"pointName": "hh:\\Configuration\\Signals:SineFast",
"value": 57.71827569129472,
"timestamp": "2020-03-04T19:03:15.193Z",
"quality": 0
},
…
]
Reading aggregated historical data (HTTP GET)
When also specifying an aggregate name and a processing interval as query string parameters, the History endpoint returns aggregated data:
GET https://<host name>/fwxapi/rest/history?PointName=hh:\Configuration\Signals:SineFast& StartDate=2020-03-04T11:25:00-0400&EndDate=2020-04-02T11:27:00-0400&AggregateName=Average&ProcessingInterval=00:01:00
The response is an array of JSON objects, each object representing a sample carrying the name, value, timestamp and quality of the requested point:
Content-Type: application/json; charset=utf-8
[
{
"pointName": "hh:\\Configuration\\Signals:SineFast",
"value": null,
"timestamp": "2020-03-04T15:27:00Z",
"quality": 2147483696
},
{
"pointName": "hh:\\Configuration\\Signals:SineFast",
"value": null,
"timestamp": "2018-03-04T15:28:00Z",
"quality": 2147483696
},
…
]
Browsing data (HTTP GET)
This endpoint allows to browse data in ICONICS Platform Services. The browse endpoint returns children of the path supplied as a parameter.
GET https://<host_name/fwxapi/rest/data/browse?path=ac:
[
{
"BrowseName": "ac:Company/",
"DisplayName": "Company",
"PointName": "ac:Company/",
"Class": 1,
"Details": null
},
{
"BrowseName": "ac:WaterIrrigation/",
"DisplayName": "WaterIrrigation",
"PointName": "ac:WaterIrrigation/",
"Class": 1,
"Details": null
},
…
]
See Also: