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
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.
- 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
It is possible to POST more complex subtrees (i.e. the new subresource may possess subresources itself):
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)
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:
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):
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:
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".
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
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).
- Back to Support Section
- Remote REST connector: Connect two OGEMA gateways via the REST interface.
- Public Applications and Drivers