As the REST API is based on open standards, any web development language can be used to access the API.
SERVICE/WEB's REST APIs provide access to resources (data entities) via URI paths. Using a REST API, the application will
make a HTTP request and parse the response. The SERVICE/WEB REST API uses XML,
JSON and JSONP as its communication format as well as standard HTTP methods like
GET, PUT, POST and DELETE (see API descriptions below to know which
methods are available for each resource). URIs for SERVICE/WEB's REST API resources have the following structure:
http://host:port/rest/api-version/resource-name
The current API version is 1.
The Service can consume and produce XML, JSON and JSONP. The content type is defined by the HTTP header value "Accept". However, especially for AJAX requests from the browser, it is not always possible to set the header values. In this case, the desired content type can be suffixed to the url, but it has to be set in front of any query parameters.
Example
Auto: http://localhost:8080/1/projects/
XML: http://localhost:8080/1/projects/.xml
JSON: http://localhost:8080/1/projects/.json
Auto: http://localhost:8080/1/projects/?someParam=value
XML: http://localhost:8080/1/projects/.xml?someParam=value
JSON: http://localhost:8080/1/projects/.json?someParam=value
JSONP
Accessing the REST APIs from a different domain via AJAX violates the same origin policy. Therefore, the JSONP technique must be used. To enable JSONP, choose the content type json and provide the query parameter "callback" within your callback function.
Any authentication working against SERVICE/WEB will also work against the REST API. The prefered authentication methods are HTTP Basic (when using SSL).
All time values are returned in nano seconds by this REST service. To define a date or a timerange, a variety of methods can be chosen. Most rest function need a timerange which is defined by the two query parameter "start" and "end".
Example: This will return the energy used between a defined point in time and the current day.
1/projects/{pname}/devices/{devid}/hist/energy/{value}/{type}?start=UTC_34235345&end=NAMED_Today
| Prefix | Description | Examples |
|---|---|---|
| UTC | A UTC timestamp in milli seconds. Optional timezone is ignored | UTC_34235345 |
| UTCSEC | A UTC timestamp in seconds. Optional timezone is ignored | UTCSEC_332435345 |
| UTCNANO | A UTC timestamp in nano seconds. This is the format used by this REST API's reponses. Optional timezone is ignored | UTCNANO_3234234532435345 |
| ISO8601 | An ISO8601 date. Too see the documentation visit the joda time homepage. When called without time information the day's beginning is used. Day's end is used only if the parameter is explicitely set to a timespan's end (e. g.paramater "end"). | ISO8601_2012-02-12, ISO8601_2012-12-24, |
| EUROPEAN | European format, either with time or without. | start=EUROPEAN_12.05.1986 results in 12.05.1986 00:00:00:00 end=EUROPEAN_12.05.1986 results in 12.05.1986 23:59:59:999 start or end=EUROPEAN_12.05.1986 12:34:10:33 results in 12.05.1986 12:34:10:33 |
| US | MM/DD/YYYY |
US_05/16/1986 US_05/16/1986 09:10:55 am US_06/25/1987 11:20:55 pm |
| NAMED | This allows you to use named timespans (e. g. last month).
Supported values:
|
start=NAMED_LastMonth&end=NAMED_LastMonth
start=NAMED_LastMonth&end=NAMED_LastMonth&anchor=EUROPEAN_12.05.1986 will result in 01.04.1986 and 30.04.1986. |
| RELATIVE | This allows you to use relative timespans like minus 3 month +50 minutes.
Supported format:
|
start=RELATIVE_-5YEAR From today minus five years. start=RELATIVE_-3MONTH+4DATE From today minus three month and plus four days. start=RELATIVE_+4MONTH&anchor=EUROPEAN_01.01.1986 results in 01.04.1986. |
The timezone default is the server installation's default timezone. To change the timezone, the "timezone" query parameter can be used. Possible values can be found here