Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseSCADA/Documentation/REST API
Starting with milestone release M2 Eclipse SCADA will have a REST API for accessing DA data using a REST based interface.
It is based on JAX-RS 1.1 and should be compatible with Gyrex. However we tested it with the OSGi Connector https://github.com/hstaudacher/osgi-jax-rs-connector
All URIs in this example assume you are using the "OSGi - JAX-RS Connector 3.1.0", although there is no special magic involved. So it *should* work with other OSGi based JAX-RS implementations supporting JAX-RS 1.1.
The "contextId" in the following URIs is the ID of the configuration object configuring the REST context. Since not all items should be exposed to the REST interface for now, the items have to be preconfigured using the CA factory "org.eclipse.scada.da.server.exporter.rest.context".
Contents
Configuration
Deployment
You will need to install and start the following bundles including their dependencies:
- org.eclipse.equinox.ds
- org.eclipse.scada.da.server.exporter.rest
In addition to you need a Hive instance in the OSGi context:
- org.eclipse.scada.da.server.osgi # if you want the OSGi based Hive
You will need some sort of OSGi HTTP Service implementation (e.g. Jetty):
- org.eclipse.equinox.http.jetty
- org.eclipse.equinox.http.registry
- org.eclipse.equinox.http.servlet
And some JAX-RS implemenation (this sample uses "OSGi - JAX-RS Connector 3.1.0"):
- com.eclipsesource.jaxrs.publisher
- com.eclipsesource.jaxrs.provider.gson
Data Types
Variant
The Variant type is encoded as a JSON Object with the fields "type" and "value":
Sample:
{ "type":"DOUBLE", "value":"0.0" }
When the Variant is deserialized it can be expressed a a JSON primitive. In this case a special "type guess" will be made (described in the Javadoc).
DataItemValue
The DataItemValue type is encoded as a JSON Object with the fields "value" and "attributes".
Sample:
{"value":{"type":"DOUBLE","value":0.0},"attributes":{"timestamp":{"type":"INT64","value":1385718698867}},"subscriptionState":"CONNECTED"}
Interface
The following commands are supported (relative to the base URI):
/{contextId}/item/{itemId} : GET
Returns the current state of the item as type "DataItemValue".
/{contextId}/item/value/{itemId} : POST
Writes the value in the body to the item. The body of the request must a "Variant".
If the write cannot be performed an exception is returned.
/{contextId}/item/attributes/{itemId} : POST
Writes the attribute (Map<String,Variant>) set to the item. The body of the request must be a "Map<String,Variant>".
If the write cannot be performed still an "OK" result is returned. It contains an object containing the result state for each attribute written. This is different than writing to an item but is due to the fact that you can write multiple attributes at the same time, some might succeed and some might fail.
Sample:
{"a":"1", "b":"2"}
Will write the attributes "a" and "b" with the values "1" (string type) and "2" (string type).