• Using the OGEMA REST Interface
Skip to end of metadata
Go to start of metadata

Access the REST interface

Access to the OGEMA resource graph and log data is available through four REST interfaces, alternatively in json or xml representation, at the following locations relative to the OGEMA host:

  • /rest/resources: retrieve a part of the resource graph (GET), create or update a resource (PUT or POST), delete resources (DELETE). Append the path of a specific resource to the URL to get information on this resource only (and its subresources, if desired)
  • /rest/recordeddata: retrieve log data for individual resources (GET);
  • /rest/patterns: retrieve pattern matches (see Advanced Resource Access (Resource Patterns)) (POST) [available in version 2.1.0]
  • /rest/resourcelists: query resources by resource type (GET; assumes a parameter type, e.g. type=org.ogema.model.prototypes.PhysicalElement) [available in version 2.1.0]

For testing and examples, you can access the servlets that support a GET request in the browser. The OGEMA demokit also comes with a debugging tool for the resources and patterns servlets, which is accessible at /org/ogema/ref-impl/rest/rest-gui/pattern.html.

The debugger comes with further instructions for using the REST servlets, and the pattern servlet debugger even provides a set of sample patterns, which can be used to get to know the syntax. There are also XML schema definitions (xsd) available at

Toggle between Json and XML

Both formats are supported by the REST servlets. To enable Json, add the following parameters to your request header:

  • Accept: "application/json"
  • Content-Type: "application/json"

For XML, use

  • Accept: "application/xml"
  • Content-Type: "application/xml"

Examples

Some examples for GET requests, which can be executed via the browser URL field. Here it is assumed that OGEMA runs on your local machine, using the standard port. Adapt host and port if necessary.

Resources servlet:

Log data

Resources by types

Pattern servlet: supports only POST requests. Use the pattern debugger, and load one of the example patterns for the POST body.

 

Page content

 

The OGEMA REST tool on the demokit start page.The OGEMA REST tool on the demokit start page.

View of a Schedule Resource in a browser window

    Part of the OGEMA resource tree in xml representation shown in a browser

 

Set a Resource value via REST

This can be done by means of a PUT request to the respective value resource. As an example, suppose there is a StringResource test_electric_light/name (if you start the demokit with unchanged settings, then the app BasicSwitchGui will create this resource). The REST path will be

https://localhost:8443/rest/resources/test_electric_light/name?user=rest&pw=rest&depth=5

Send a GET to this address in order to verify that the resource exists; if you get a 404-response, the resource is not available. Then send the following PUT-request:

The response should contain the resource in XML-representation, with the modified value.

Note:

  • it is important to adapt the xsi:type-attribute in the <og:resource>-tab to the resource type; the values correspond to the simple resource type names, such as StringResource, FloatResource, IntegerResource, BooleanResourcen, TimeResource. This attribute is only needed for value resources.
  • instead of a PUT-request, you can send a POST-request with the same content to the parent resource (test_electric_light, in the example).

Create a subresource via REST

A subresource can be created by means of a POST-request to the parent resource. Let's assume there is a resource test_electric_light, and we want to create a subresource called dummy. Then we'd send a POST to

https://localhost:8443/rest/resources/test_electric_light?user=rest&pw=rest&depth=5

with body

POST body for value subresource

It is possible to POST more complex subtrees (i.e. the new subresource may possess subresources itself):

POST body for complex subresource

Example work flow

A typical use case for the REST interface is that one wants to access the OGEMA database from an external device, such as a smartphone. Let's say, you are developing a smartphone application that allows to navigate by room, and displays information about all the devices contained in a room. So, first of all, you need to know which rooms are available. The simplest solution would be to send a request to the "Resources by types" REST servlet:

Here, host and port are shown again for the local machine, in a real application they must be configurable, of course, just like the user and pw parameters.
However, there may be further information relevant to your application. For instance, in case the user has provided names for the rooms, you may want to display these as well (instead of the potentially cryptic OGEMA resource path), or you might instead display the type of the rooms, if they are provided (bathroom, childrens' room, kitchen, etc.). In this case, you are better off using the pattern servlet. It also allows you to introduce more advanced features such as paging (showing only a subset of the rooms on a single page, and allow the user to browse through the pages): send a POST request to

with the following body (the example is available in the debugging tool - select Room Pattern)

RoomPattern - click to expand  Expand source

Note that both subresource fields name and roomType are optional, hence there is no guarantee that they will actually be provided in the answer. The next xml block shows an example of what the answer could look like:

Room Pattern response - click to expand  Expand source

In this example, there are three rooms, one which has a human readable name, one with a type (type = 1 means living room, cf. the Apidoc), and one that does not provide any further information at all. You can now display the rooms in your application. 

Now suppose that the user clicks on one of the rooms in your smartphone application. In this case, you may want to open a new page/view which lists all the devices available in this room. For this purpose, we can use again the pattern servlet. Let's assume the resource path of the selected room is myRoom (a top-level resource). The following pattern request will give us all devices contained in this room (note the location parameter in the field location/room, which restricts the set of PhysicalElement resources returned by the request to those whose location/room subresource links to our selected room):

PhysicalElement request - click to expand  Expand source

The response will give us all devices located in myRoom, together with a human readable name, if available. Now they can be displayed in the application. Here is a sample response with two matches:

PhysicalElements response  Expand source

Read Timeseries values

Using the /rest/recordeddata endpoint we can query the list of logged resources. The response is a plain text file with lines the resource paths:

Appending the path of a logged resource to the endpoint will lead to the data points of the time series being returned (in xml format, by default).

We can restrict the range of the time series by specifying the parameters start and/or end, where the timestamp may be specified either as a Long value (milliseconds since 1/1/1970) or as an ISO String with optional parts; e.g. "2017-08-07" or "2017-08-07T01:14:02" or "2017-08-07T01:14:02.234Z".

Supported options

All servletes take a parameter user and pw. Access to the REST interface requires a so-called machine-user, with permissions to access the relevant parts of the resource graph (see user management; in the demokit, it is available at 
/ogema/frameworkadminindex/index.html#/users
, as part of the framework administration). If you are starting the system with security disabled, the user and pw parameters are ignored and not required.

Resources servlet (/rest/resources)

  • depth (non-negative integer): specify the depth of the resource graph; defaults to 0, in which case only the requested resource is returned, with subresources added as links, respectively all top-level resources if the request goes to the base URL.
  • references (boolean): resolve references? Defaults to false, in which case referencing resources are added as links (which only provide information on type, path and location). Note that cyclic references are never resolved, so you may get resource links in your result, even though the parameter is true.
  • schedules (boolean): show schedule values? Defaults to false, unless the schedule is the target resource for this request. Note that schedule values can significantly increase the size of the response.

The parameters are mostly relevant to GET requests, but also determine the form of the response in case of PUT or POST.

Resource types servlet (/rest/resourcelists)

  • type (String, mandatory): the full resource type name, such as org.ogema.model.prototypes.PhysicalElement.
  • recursive (boolean): get only top-level resources (respectively, direct subresources of the queried resource path), or recursive ones as well? Defaults to true.

Pattern servlet (/rest/patterns)

  • recursive (boolean): get only top-level resources (recursive = false), or subresources as well? Defaults to false.
  • maxHits (non-negative integer): restrict the number of pattern matches returned. Defaults to Integer.MAX_VALUE.
  • from (non-negative integer): start index of the returned pattern matches. Defaults to 0.

Log data servlet (/rest/recordeddata)

  • start (long, time in ms since Jan 1st 1970): start time of returned values; default 0
  • end (long, time in ms since Jan 1st 1970): end time of returned values: default Long.MAX_VALUE
  • interval (long, time interval in ms between adjacent points): defaults to configured logging interval
  • mode (String): allowed values (see OGEMA enum org.ogema.core.recordeddata.ReductionMode): NONE (default), AVERAGE, MAXIMUM_VALUE, MINIMUM_VALUE, MIN_MAX_VALUE

 

 

The REST debugging tool

The REST debugging tool

 

 

Reading Data via a Web Browser

Sometimes, a framework operator may want to access or export resource data even though no application is installed on the framework that provides this option. A typical case in which this becomes necessary is debugging during development time. Provided the user has the required permissions to access the resource in the first place (which is usually the case for debugging during developtment time) a simple alternative to writing an explicit OGEMA application providing the data is using the REST interface of the OGEMA system. The simplest case of such an access is using a standard web browser and calling the URL of the respective resource. The resource data are then shown in the browser window and can be exported to the hard disk by saving the web page via the browser menu.

Post-processing Schedule Data

Usually, schedules are exported to plot them with some program. For plotting, the exported XML format is not very convenient. Linux users can convert an exported file schedule.xml to a three-column file schedule.dat with the command

cat schedule.xml | sed 's/<entry/\n<entry/g' | sed 's/[<>]/\ /g' | cut -d" " -f6,10,14 > schedule.dat

and then manually deleting the first lines of the output (that do not contain data - the lines are obvious in a text editor).

 

Next


 

  • No labels