REST-API

WEB REST API

Version: 3.1.0

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:

[Link]

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: [Link]
XML: [Link]
JSON: [Link]

Auto: [Link]
XML: [Link]
JSON: [Link]

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?start=UTC_34235345&end=NAMED
_Today
Prefi
Description Examples
x
A UTC timestamp in milli seconds.
UTC UTC_34235345
Optional timezone is ignored
UTC A UTC timestamp in seconds.
UTCSEC_332435345
SEC Optional timezone is ignored
A UTC timestamp in nano seconds.
UTC
This is the format used by this REST
NAN UTCNANO_3234234532435345
API's reponses. Optional timezone is
O
ignored
An ISO8601 date. Too see the
documentation visit the joda time
homepage. When called without time
ISO8 information the day's beginning is ISO8601_2012-02-12, ISO8601_2012-
601 used. Day's end is used only if the 12-24,
parameter is explicitely set to a
timespan's end (e. [Link]
"end").
start=EUROPEAN_12.05.1986 results
in 12.05.1986 00:00:00:00
EUR
European format, either with time or end=EUROPEAN_12.05.1986 results in
OPE
without. 12.05.1986 23:59:59:999 start or
AN
end=EUROPEAN_12.05.1986
12:34:10:33 results in 12.05.1986
Prefi
Description Examples
x
12:34:10:33
US_05/16/1986
US MM/DD/YYYY US_05/16/1986 09:10:55 am
US_06/25/1987 11:20:55 pm
This allows you to use named
timespans (e. g. last month).
Supported values:

• Today
• Yesterday
• ThisWeek
• LastWeek
start=NAMED_LastMonth&end=NAME
• ThisMonth
D_LastMonth
• LastMonth
NAM start=NAMED_LastMonth&end=NAME
• ThisQuarter
ED D_LastMonth&anchor=EUROPEAN_12.
• LastQuarter
05.1986 will result in 01.04.1986 and
• ThisYear
30.04.1986.
• 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.
This allows you to use relative
timespans like minus 3 month +50
minutes. Supported format:

• change := amount+
• amount:= sign? amount type
start=RELATIVE_-5YEAR From today
• sign := '+' | '-'
minus five years.
• amount := 0-9*
start=RELATIVE_-3MONTH+4DATE
REL • type :=
From today minus three month and plus
ATIV YEAR|MONTH|WEEK_OF_YE
four days.
E AR|WEEK_OF_MONTH|DATE
start=RELATIVE_+4MONTH&anchor=E
|DAY_OF_YEAR
UROPEAN_01.01.1986 results in
DAY_OF_WEEK|
01.04.1986.
DAY_OF_WEEK_IN_MONTH|
HOUR| HOUR_OF_DAY|
MINUTE| SECOND

For further documentation use the

java calendar object documentation.

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

o [Link] [GET, PUT]

o [Link] [GET, DELETE]

 [Link] [GET]

o [Link] [GET]

o [Link]
ergy
 [Link]
hist/energy/{value}/{type} [GET]

o [Link]
ents [GET]

o [Link]
gs [GET]

o [Link]
quences
 [Link]
hist/sequences/{sequenceType} [GET]
 o [Link]
nsients [GET]

o [Link]
lues [GET]
 [Link]
hist/values/{value}/{type}/{timebase} [GET]

o [Link]
 [Link] [GET]

Resources
/rest/1/projects
Methods

GET

Get all loaded projects.

available response representations:

• 200 - application/json (projects) [collapse]

Example

[ { "name": "ProjName", "path": "/var/projects/aproj",

"numberOfDevices": 32 }, { "name": "ProjName2", "path":
"/var/projects/bproj", "numberOfDevices": 23 } ]

Returns a list of all loaded projects.

PUT

Load a project into the server.

acceptable request representations:

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

"/projects/MyProject"

available response representations:

• 200 - application/json [collapse]

 The project was loaded successfully.

• 400 [collapse]

The path could not be found or is not a gridvis project. Also licence may be
missing.

• 403 [collapse]

You do not have the necessary permission.

/rest/1/projects/{pname}
Methods

GET

Retrieve information about a loaded project.

available response representations:

• 200 - application/json (project) [collapse]

Example

{ "name": "ProjName", "path": "/var/projects/aproj",

"numberOfDevices": 32 }

Returns a full representation of a project.

• 404 [collapse]

project name not found.

DELETE

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

available response representations:

• 204 [collapse]

ok, removed on next restart

• 404 [collapse]

project name not found.

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

Retrieve information about all devices.

available response representations:

• 200 - application/json (DeviceEnt) [collapse]

Example

{ "name": "UMG508 Main Supply", "id": 33, "type": "JanitzaUMG508",

"connectionString": "ModbusTCP:umg508-
[Link]|502|5000|2|TCP|ModTCP|3", "serialNr": "424-444" }

Returns a representation of all devices.

• 404 [collapse]

project name not found.

/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) [collapse]

Example

{ "name": "UMG508 Main Supply", "id": 33, "type": "JanitzaUMG508",

"connectionString": "ModbusTCP:umg508-
[Link]|502|5000|2|TCP|ModTCP|3", "serialNr": "424-444" }

Returns a full representation of a device.

• 404 [collapse]

project name not found.

/rest/1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}
resource-wide template parameters
parameter value description
value string a value name, check /hist/values
a type, e.g. L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13, SUM14
type string
and others.

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 (EnergyEnt) [collapse]

Example

{ "valueType": { "value": "ActiveEnergy", "typeName": "L1", "type":

"L1", "unit": "Wh", "valueName": "Active Energy" }, "startTime":
123456789, "endTime": 234567890, "unit": "kWh", "energy": 2774 }

Returns the sum of all found values.

• 204 [collapse]

no content for the requested timespan

/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

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

available response representations:

 • 200 (EventEnt) [collapse]
Example

[ { "input": "L3", "startTime": 342344, "endTime": 24235256, "min":

224, "avg": 234, "max": 310, "limit": 230, "eventType": "CurrentOver"
}, { "input": "L3", "startTime": 342344, "endTime": 24235256, "min":
224, "avg": 234, "max": 310, "limit": 230, "eventType": "CurrentOver"
} ]

Returns a list of all found events.

• 204 [collapse]

no content for the requested timespan

• 400 [collapse]

bad request, e.g. no query param(s) for "type"

/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) [collapse]

Example

[ { "startTime": 123456789, "endTime": 234567890, "flagType": [

"LostWindow", "ClockNotSet" ] }, { "startTime": 123456789, "endTime":
234567890, "flagType": [ "LostWindow", "ClockNotSet" ] } ]

Returns a list of all found flags.

• 204 [collapse]

no content for the requested timespan

/rest/1/projects/{pname}/devices/{devid}/hist/sequences/{sequenceTyp
e}
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) [collapse]

Example

[ { "type": "EffectiveValues", "reason": "Event", "valueType": {

"value": "I_Effective", "typeName": "L2", "type": "L2", "unit": "A",
"valueName": "Current effective" }, "startTime": 123456789,
"endTime": 234567890, "pretrigger": 500, "values": [ 32.11193,
32.325405 ], "sampleRate": 99.98306 }, { "type": "EffectiveValues",
"reason": "Event", "valueType": { "value": "I_Effective", "typeName":
"L2", "type": "L2", "unit": "A", "valueName": "Current effective" },
"startTime": 123456789, "endTime": 234567890, "pretrigger": 500,
"values": [ 32.11193, 32.325405 ], "sampleRate": 99.98306 } ]

Returns a list of all found sequences.

• 204 [collapse]

no content for the requested timespan

/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) [collapse]

Example

[ { "type": "Slope", "valueType": { "value": "U_Effective",

"typeName": "L1", "type": "L1", "unit": "V", "valueName": "Voltage
effective" }, "startTime": 342344, "endTime": 3423443, "energy":
"NaN", "max": 420 }, { "type": "Slope", "valueType": { "value":
"U_Effective", "typeName": "L1", "type": "L1", "unit": "V",
"valueName": "Voltage effective" }, "startTime": 342344, "endTime":
3423443, "energy": "NaN", "max": 420 } ]

Returns a list of all found transients.

• 204 [collapse]
 no content for the requested timespan

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

GET

Retrieve list of all historical values.

available response representations:

• 200 - application/json (ValueDescriptionEnt) [collapse]

Example

[ { "id": 34, "valueType": { "value": "U_Effective", "typeName":

"L1", "type": "L1", "unit": "V", "valueName": "Voltage effective" },
"online": false, "timebase": 900 }, { "id": 34, "valueType": {
"value": "U_Effective", "typeName": "L1", "type": "L1", "unit": "V",
"valueName": "Voltage effective" }, "online": false, "timebase": 900
} ]

Returns a full representation of a values entity.

• 404 [collapse]

project name not found.

/rest/1/projects/{pname}/devices/{devid}/hist/values/{value}/{type}/{tim
ebase}
resource-wide template parameters

parameter value description

value string a value name, check /hist/values
a type, e.g. Overall, L1, L2, L3, L4, L5, L2L1, L3L2, L1L3, SUM13,
type string
SUM14, Main, Aux and others.
timebase int The timebase in seconds of the recording, in most cases 900.

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

 boolean
online Whether the value was recorded online.
Default: false

available response representations:

• 200 (ValueListEnt) [collapse]

Example

{ "valueType": { "value": "U_Effective", "typeName": "L1-L3", "type":

"L1L3", "unit": "V", "valueName": "Voltage effective" }, "values": [
{ "startTime": 234234, "endTime": 234924234, "min": 50.04, "avg":
230.55, "max": 310 }, { "startTime": 234234, "endTime": 234924234,
"min": 50.04, "avg": 230.55, "max": 310 } ], "online": true,
"timebase": 900 }

Returns a list of all found values.

• 204 [collapse]

no content for the requested timespan

/rest/common/info/version/full
Methods

GET

Retrieve information about the server version

available response representations:

• 200 - application/json [collapse]

Returns the version string.