Versions Compared

Old Version 31

changes.mady.by.user Georg Schneider

Saved on

compared with

New Version 32

changes.mady.by.user Georg Schneider

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Mittels Scroll Versions veröffentlicht aus dem Bereich GVH und Version 1.0.
Sv translation
languagede

Inhalt
maxLevel2
minLevel2
indent0px
stylenonr



REST-API

Info
titleHinweis
  • Sie rufen die REST-Dokumentation zusätzlich auf, indem Sie /rest/doc/ an die url des Diensts anhängen.
    Beispiel: http://localhost:8080/rest/doc/
  • Die REST-Dokumentation steht nur in englischer Sprache zur Verfügung.
REST-API

WEB REST API

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parameter
value
description

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated 
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parameter
value
description

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parameter
value
description

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parameter
value
description

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parameter
value
description

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated 
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parameter
value
description

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parameter
value
description

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parameter
value
description

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]





Sv translation
languageen

Inhalt
maxLevel2
minLevel2
indent0px
stylenone



REST-API

Info
titleNote
  • You also open the REST documentation by appending /rest/doc/ to the url of the Service.
    Example: http://localhost:8080/rest/doc/
  • The REST documentation is available in English only.
REST-API

WEB REST API

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
PrefixDescriptionExamples
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parametervaluedescription

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parametervaluedescription

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parametervaluedescription

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parametervaluedescription

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parametervaluedescription

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parametervaluedescription

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parametervaluedescription

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parametervaluedescription

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parametervaluedescription

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parametervaluedescription

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
PrefixDescriptionExamples
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parametervaluedescription

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parametervaluedescription

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parametervaluedescription

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parametervaluedescription

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parametervaluedescription

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parametervaluedescription

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parametervaluedescription

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parametervaluedescription

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parametervaluedescription

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parametervaluedescription

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]



Sv translation
languagees

Inhalt
maxLevel2
minLevel2
indent0px
stylenone



REST-API

Info
titleNota
  • También se puede acceder a la documentación REST añadiendo /rest/doc/ a la url del servicio.
    Ejemplo: http://localhost:8080/rest/doc/
  • La documentación REST sólo está disponible en inglés.
REST-API

WEB REST API

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parameter
value
description

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated 
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parameter
value
description

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parameter
value
description

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parameter
value
description

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parameter
value
description

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated 
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parameter
value
description

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parameter
value
description

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parameter
value
description

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]




Sv translation
languageit

Inhalt
maxLevel2
minLevel2
indent0px
stylenone



REST-API

Info
titleNota
  • È possibile richiamare la documentazione REST aggiungendo /rest/doc/ all'url del servizio.
    Esempio: http://localhost:8080/rest/doc/
  • La documentazione REST è disponibile solo in inglese.
REST-API

WEB REST API

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parameter
value
description

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated 
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parameter
value
description

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parameter
value
description

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parameter
value
description

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]

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.

Getting started

As the REST API is based on open standards, any web development language can be used to access the API.

Structure of the REST URIs

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.

Content negotiation

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.

Authentication

Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).

Date and Time

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
UTCA UTC timestamp in milli seconds. Optional timezone is ignoredUTC_34235345
UTCSECA UTC timestamp in seconds. Optional timezone is ignoredUTCSEC_332435345
UTCNANOA UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignoredUTCNANO_3234234532435345
ISO8601An 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,
EUROPEANEuropean 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
USMM/DD/YYYYUS_05/16/1986
US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
NAMEDThis allows you to use named timespans (e. g. last month). Supported values:
  • Today
  • Yesterday
  • ThisWeek
  • LastWeek
  • ThisMonth
  • LastMonth
  • ThisQuarter
  • LastQuarter
  • ThisYear
  • LastYear
These values are calculated relative to the current server time. But this anchor in time can be changed by the "anchor" query parameter. The anchor accepts any time method, especially RELATIVE.		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.
RELATIVEThis allows you to use relative timespans like minus 3 month +50 minutes. Supported format:
  • change := amount+
  • amount:= sign? amount type
  • sign := '+' | '-'
  • amount := 0-9*
  • type := YEAR|MONTH|WEEK_OF_YEAR|WEEK_OF_MONTH|DATE|DAY_OF_YEAR DAY_OF_WEEK| DAY_OF_WEEK_IN_MONTH| HOUR| HOUR_OF_DAY| MINUTE| SECOND
For further documentation use the java calendar object documentation.		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.
Timezone

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

Index

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.

Resources

/rest/1/projects

Methods

GET

Get all loaded projects.

available response representations:

200
  • application/json (projects) [expand]

PUT

Load a project into the server.

acceptable request representations:

  • text/plain (http body as a file path on the server's file system) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}

Methods

DELETE

Mark a project not to be loaded on next server restart.

available response representations:

401

available response representations:

204

available response representations:

404

GET

Retrieve information about a loaded project.

available response representations:

200
  • application/json (project) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices

Methods

GET

Retrieve information about all devices.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about a device.

available response representations:

200
  • application/json (DeviceEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/connectiontest

resource-wide template parameters
parameter
value
description

devid

int

the numeric device id, check GET /devices

pname

string

project name

Methods

GET

Retrieve information about the connection of a device.

available response representations:

200
  • application/json (ConnectionTestEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}

resource-wide template parameters
parameter
value
description

type

string

a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14 and others.

value

string

a value name, check /hist/values

Methods

GET

Get energy consume for given value and type from Device within given timespan. This method supports the timespan parameters, see documentation.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/events

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/events?type

Returns events for a given timespan. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

type

string

Repeatable. A list of event types. Current list: VoltageOver, VoltageUnder, VoltageOutage, VoltageFastChange, CurrentOver, PowerFailure, PowerRecovery, DigitalInputActivated, DigitalInputDeactivated, ComparatorOutputActivated, ComparatorOutputDeactivated, TariffActivated, EmaxChannelActivated, EmaxChannelDeactivated 
Example:: events?type=VoltageOutage&type=VoltageOver

available response representations:

200

available response representations:

400

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/flags

Methods

GET

Get Flags from the device. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (FlagEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceType}

resource-wide template parameters
parameter
value
description

sequenceType

string

a SequenceType, either Waveform or EffectiveValues

Methods

GET

Get sequence data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (SequenceEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/transients

Methods

GET

Get transient data. This method supports the timespan parameters, see documentation.

available response representations:

200
  • application/json (TransientEnt) [expand]

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/hist/values

Methods

GET

Retrieve list of all historical values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int

The timebase in seconds of the recording, in most cases 900.

type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{timebase}?online

Get historical data. This method supports the timespan parameters, see documentation.

request query parameters
parameter
value
description

online

boolean

Default: false

Whether the value was recorded online.

available response representations:

200

available response representations:

204

/rest/1/projects/{pname}/devices/{devid}/manualinput

Manual input device endpoint.

Methods

GET

Retrieve list of all manual input values.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/manualinput/{value}/{type}/{timebase}

resource-wide template parameters
parameter
value
description

timebase

int


type

string

a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14, Main, Aux and others.

value

string

a value name, check /hist/values

Methods

GET

Retrieve the information about the manual input device.

available response representations:

200
  • application/json (ValueDescriptionEnt) [expand]

available response representations:

400

available response representations:

404

POST

Saves value to historical data.

acceptable request representations:

  • application/xml (inputvalue) [expand]
  • application/json (inputvalue) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/online/values

Methods

GET

Retrieve list of all online value types.

available response representations:

200
  • application/json (ValueTypeEnt) [expand]

available response representations:

404

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/settings

Methods

GET

Get settings for online recording values of device.

available response representations:

200
  • text/plain (OnlRecValueEnt) [expand]

POST

Saves settings for online recording values of device.

acceptable request representations:

  • application/xml (onlRecValues) [expand]
  • application/json (onlRecValues) [expand]

available response representations:

200

available response representations:

400

available response representations:

401

/rest/1/projects/{pname}/devices/{devid}/onlinerecord/statistics

Methods

GET

Get statistics for online recording values of device.

available response representations:

200
  • application/json (OnlRecValueStatisticEnt) [expand]

/rest/1/projects/{pname}/onlinevalues

Methods

GET

/rest/1/projects/{pname}/onlinevalues?value&appendValueType&timeout&timeliness

Fetch 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.

request query parameters
parameter
value
description

value

string

Repeatable. A list of values. Each value is specified by the query param "value" and the query content of a semicolon separated list of:

  • The device id
  • A value e.g. U_Effective,I_Effective, PowerActive
  • A type e.g. L1. The type is also repeatable by comma, eg. L1,L2,L3

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

boolean

A Boolean indicating appending the ValueType. Example: /1/projects/{pname}/onlinevalues?value={devid};U_Effective;L1,L2,L3&appendValueType=true

timeout

int

Default: 500

Maximum wait time for values in milli seconds for all value to become timeliness.

timeliness

int

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:

200

available response representations:

400

/rest/1/threaddump

Methods

GET

Get a thread dump.

available response representations:

/rest/1/valuetypes

Methods

GET

Retrieve information about all available value types.

available response representations:

200

/rest/1/valuetypes/{subtype}

resource-wide template parameters
parameter
value
description

subtype

string

A subtype from the list /rest/valuetypes/subtypes

Methods

GET

Retrieve a value types for a specific subtype.

available response representations:

200

/rest/1/valuetypes/subtypes

Methods

GET

All subtypes for /rest/valuetypes/{subtype}

available response representations:

200

/rest/common/info/language/test

Methods

GET

available response representations:

/rest/common/info/version/full

Methods

GET

Retrieve information about the server version

available response representations:

200

application/json [expand]