|
This is the reference document for the REST API and resources provided by SERVICE/WEB. The REST APIs are for developers who want to integrate SERVICE/WEB with other standalone or web applications and for administrators who want to script interactions with the SERVICE/WEB server.
As the REST API is based on open standards, any web development language can be used to access the API.
SERVICE/WEB's REST APIs provide access to resources (data entities) via URI paths. Using a REST API, the application will make a HTTP request and parse the response. The SERVICE/WEB REST API uses XML, JSON and JSONP as its communication format as well as standard HTTP methods like GET
, PUT
, POST
and DELETE
(see API descriptions below to know which methods are available for each resource). URIs for SERVICE/WEB's REST API resources have the following structure:
http://host:port/rest/api-version/resource-name
The current API version is 1
.
There is a WADL document containing the documentation for each resource in the SERVICE/WEB REST API. It is available here.
The Service can consume and produce XML, JSON and JSONP. The content type is defined by the HTTP header value "Accept". However, especially for AJAX requests from the browser, it is not always possible to set the header values. In this case, the desired content type can be suffixed to the url, but it has to be set in front of any query parameters.
Example
Auto: http://localhost:8080/1/projects/ XML: http://localhost:8080/1/projects/.xml JSON: http://localhost:8080/1/projects/.json Auto: http://localhost:8080/1/projects/?someParam=value XML: http://localhost:8080/1/projects/.xml?someParam=value JSON: http://localhost:8080/1/projects/.json?someParam=value
JSONP
Accessing the REST APIs from a different domain via AJAX violates the same origin policy. Therefore, the JSONP technique must be used. To enable JSONP, choose the content type json and provide the query parameter "callback" within your callback function.
Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).
All time values are returned in nano seconds by this REST service. To define a date or a timerange, a variety of methods can be chosen. Most rest function need a timerange which is defined by the two query parameter "start" and "end".
Example: This will return the energy used between a defined point in time and the current day.
1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}?start=UTC_34235345&end=NAMED_Today
Prefix | Description | Examples |
---|---|---|
UTC | A UTC timestamp in milli seconds. Optional timezone is ignored | UTC_34235345 |
UTCSEC | A UTC timestamp in seconds. Optional timezone is ignored | UTCSEC_332435345 |
UTCNANO | A UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignored | UTCNANO_3234234532435345 |
ISO8601 | An ISO8601 date. Too see the documentation visit the joda time homepage. When called without time information the day's beginning is used. Day's end is used only if the parameter is explicitely set to a timespan's end (e. g.paramater "end"). | ISO8601_2012-02-12, ISO8601_2012-12-24, |
EUROPEAN | European format, either with time or without. | start=EUROPEAN_12.05.1986 results in 12.05.1986 00:00:00:00 end=EUROPEAN_12.05.1986 results in 12.05.1986 23:59:59:999 start or end=EUROPEAN_12.05.1986 12:34:10:33 results in 12.05.1986 12:34:10:33 |
US | MM/DD/YYYY | US_05/16/1986 US_05/16/1986 09:10:55 am US_06/25/1987 11:20:55 pm |
NAMED | This allows you to use named timespans (e. g. last month). Supported values:
| start=NAMED_LastMonth&end=NAMED_LastMonth start=NAMED_LastMonth&end=NAMED_LastMonth&anchor=EUROPEAN_12.05.1986 will result in 01.04.1986 and 30.04.1986. |
RELATIVE | This allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
| start=RELATIVE_-5YEAR From today minus five years. start=RELATIVE_-3MONTH+4DATE From today minus three month and plus four days. start=RELATIVE_+4MONTH&anchor=EUROPEAN_01.01.1986 results in 01.04.1986. |
The timezone default is the server installation's default timezone. To change the timezone, the "timezone" query parameter can be used. Possible values can be found here
The WEB REST API allows access to projects, devices and their data.
Die WEB REST API erlaubt den Zugriff auf Projekte, Geräte und Daten.
Get all loaded projects.
available response representations:
200parameter | value | description |
---|---|---|
devid | the numeric device id, check GET /devices | |
pname | project name |
parameter | value | description |
---|---|---|
devid | the numeric device id, check GET /devices | |
pname | project name |
parameter | value | description |
---|---|---|
type | a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others. | |
value | a value name, check /hist/values |
Returns events for a given timespan. This method supports the timespan parameters, see documentation.
parameter | value | description |
---|---|---|
type | Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated |
available response representations:
200available response representations:
400available response representations:
204parameter | value | description |
---|---|---|
sequenceType | a SequenceType, either Waveform or EffectiveValues |
parameter | value | description |
---|---|---|
timebase | The timebase in seconds of the recording, in most cases 900. | |
type | a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others. | |
value | a value name, check /hist/values |
Get historical data. This method supports the timespan parameters, see documentation.
parameter | value | description |
---|---|---|
online | Default: false | Whether the value was recorded online. |
available response representations:
200available response representations:
204Manual input device endpoint.
parameter | value | description |
---|---|---|
timebase | ||
type | a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others. | |
value | a value name, check /hist/values |
Get settings for online recording values of device.
available response representations:
200Get statistics for online recording values of device.
available response representations:
200Fetch online value(s) from device(s). This call will return immediately if all requested data is "timeliness". If not all data is timeliness the request wait, but no longer than the given timeout. If a timeout occur all known data is returned. There is no guarantee that the values are measured at this same point in time. It simply the last known value known to the application. The value is as fast as possible regarding its source device.
parameter | value | description |
---|---|---|
value | Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:
Example:: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&value=23;PowerActive;L1 For possible value and type combinations please refer to 1/valuetypes | |
appendValueType | A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true | |
timeout | Default: 500 | Maximum wait time for values in milli seconds for all value to become timeliness. |
timeliness | Default: 60000 | Defines the maxium time between the request and the last update on a value. If the value was updated in between this period it is considered timeliness. If all value are timeliness the request can return. |
available response representations:
200available response representations:
400Retrieve information about all available value types.
available response representations:
200parameter | value | description |
---|---|---|
subtype | A subtype from the list /rest/valuetypes/subtypes |
Retrieve a value types for a specific subtype.
available response representations:
200All subtypes for /rest/valuetypes/{subtype}
available response representations:
200Retrieve information about the server version
available response representations:
200
This is the reference document for the REST API and resources provided by SERVICE/WEB. The REST APIs are for developers who want to integrate SERVICE/WEB with other standalone or web applications and for administrators who want to script interactions with the SERVICE/WEB server.
As the REST API is based on open standards, any web development language can be used to access the API.
SERVICE/WEB's REST APIs provide access to resources (data entities) via URI paths. Using a REST API, the application will make a HTTP request and parse the response. The SERVICE/WEB REST API uses XML, JSON and JSONP as its communication format as well as standard HTTP methods like GET
, PUT
, POST
and DELETE
(see API descriptions below to know which methods are available for each resource). URIs for SERVICE/WEB's REST API resources have the following structure:
http://host:port/rest/api-version/resource-name
The current API version is 1
.
There is a WADL document containing the documentation for each resource in the SERVICE/WEB REST API. It is available here.
The Service can consume and produce XML, JSON and JSONP. The content type is defined by the HTTP header value "Accept". However, especially for AJAX requests from the browser, it is not always possible to set the header values. In this case, the desired content type can be suffixed to the url, but it has to be set in front of any query parameters.
Example
Auto: http://localhost:8080/1/projects/ XML: http://localhost:8080/1/projects/.xml JSON: http://localhost:8080/1/projects/.json Auto: http://localhost:8080/1/projects/?someParam=value XML: http://localhost:8080/1/projects/.xml?someParam=value JSON: http://localhost:8080/1/projects/.json?someParam=value
JSONP
Accessing the REST APIs from a different domain via AJAX violates the same origin policy. Therefore, the JSONP technique must be used. To enable JSONP, choose the content type json and provide the query parameter "callback" within your callback function.
Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).
All time values are returned in nano seconds by this REST service. To define a date or a timerange, a variety of methods can be chosen. Most rest function need a timerange which is defined by the two query parameter "start" and "end".
Example: This will return the energy used between a defined point in time and the current day.
1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}?start=UTC_34235345&end=NAMED_Today
Prefix | Description | Examples |
---|---|---|
UTC | A UTC timestamp in milli seconds. Optional timezone is ignored | UTC_34235345 |
UTCSEC | A UTC timestamp in seconds. Optional timezone is ignored | UTCSEC_332435345 |
UTCNANO | A UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignored | UTCNANO_3234234532435345 |
ISO8601 | An ISO8601 date. Too see the documentation visit the joda time homepage. When called without time information the day's beginning is used. Day's end is used only if the parameter is explicitely set to a timespan's end (e. g.paramater "end"). | ISO8601_2012-02-12, ISO8601_2012-12-24, |
EUROPEAN | European format, either with time or without. | start=EUROPEAN_12.05.1986 results in 12.05.1986 00:00:00:00 end=EUROPEAN_12.05.1986 results in 12.05.1986 23:59:59:999 start or end=EUROPEAN_12.05.1986 12:34:10:33 results in 12.05.1986 12:34:10:33 |
US | MM/DD/YYYY | US_05/16/1986 US_05/16/1986 09:10:55 am US_06/25/1987 11:20:55 pm |
NAMED | This allows you to use named timespans (e. g. last month). Supported values:
| start=NAMED_LastMonth&end=NAMED_LastMonth start=NAMED_LastMonth&end=NAMED_LastMonth&anchor=EUROPEAN_12.05.1986 will result in 01.04.1986 and 30.04.1986. |
RELATIVE | This allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
| start=RELATIVE_-5YEAR From today minus five years. start=RELATIVE_-3MONTH+4DATE From today minus three month and plus four days. start=RELATIVE_+4MONTH&anchor=EUROPEAN_01.01.1986 results in 01.04.1986. |
The timezone default is the server installation's default timezone. To change the timezone, the "timezone" query parameter can be used. Possible values can be found here
The WEB REST API allows access to projects, devices and their data.
Die WEB REST API erlaubt den Zugriff auf Projekte, Geräte und Daten.
Get all loaded projects.
available response representations:
200parameter | value | description |
---|---|---|
devid | the numeric device id, check GET /devices | |
pname | project name |
parameter | value | description |
---|---|---|
devid | the numeric device id, check GET /devices | |
pname | project name |
parameter | value | description |
---|---|---|
type | a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others. | |
value | a value name, check /hist/values |
Returns events for a given timespan. This method supports the timespan parameters, see documentation.
parameter | value | description |
---|---|---|
type | Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated |
available response representations:
200available response representations:
400available response representations:
204parameter | value | description |
---|---|---|
sequenceType | a SequenceType, either Waveform or EffectiveValues |
parameter | value | description |
---|---|---|
timebase | The timebase in seconds of the recording, in most cases 900. | |
type | a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others. | |
value | a value name, check /hist/values |
Get historical data. This method supports the timespan parameters, see documentation.
parameter | value | description |
---|---|---|
online | Default: false | Whether the value was recorded online. |
available response representations:
200available response representations:
204Manual input device endpoint.
parameter | value | description |
---|---|---|
timebase | ||
type | a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others. | |
value | a value name, check /hist/values |
Get settings for online recording values of device.
available response representations:
200Get statistics for online recording values of device.
available response representations:
200Fetch online value(s) from device(s). This call will return immediately if all requested data is "timeliness". If not all data is timeliness the request wait, but no longer than the given timeout. If a timeout occur all known data is returned. There is no guarantee that the values are measured at this same point in time. It simply the last known value known to the application. The value is as fast as possible regarding its source device.
parameter | value | description |
---|---|---|
value | Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:
Example:: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&value=23;PowerActive;L1 For possible value and type combinations please refer to 1/valuetypes | |
appendValueType | A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true | |
timeout | Default: 500 | Maximum wait time for values in milli seconds for all value to become timeliness. |
timeliness | Default: 60000 | Defines the maxium time between the request and the last update on a value. If the value was updated in between this period it is considered timeliness. If all value are timeliness the request can return. |
available response representations:
200available response representations:
400Retrieve information about all available value types.
available response representations:
200parameter | value | description |
---|---|---|
subtype | A subtype from the list /rest/valuetypes/subtypes |
Retrieve a value types for a specific subtype.
available response representations:
200All subtypes for /rest/valuetypes/{subtype}
available response representations:
200Retrieve information about the server version
available response representations:
200