CMe3100 REST API Plugin
This document describes Elvaco Rest API and interactions within resources provided by CMe3100 product. Elvaco Rest API provides access to resources (data entities) via URL paths. All actions through API are done by using standard HTTP methods GET, POST, PUT, and DELETE. Standard HTTP response codes used to indicate success and error conditions.
Request body data is expected to be in JSON, and response body data is returned as JSON.
Status object as JSON returns when any operation executed without returning result entity.
{
status: Status text
}
Status text: Record(s) not found / Parameter(s) not found / Success/ Error
HTTP status codes respectively: 404 Not found / 404 Not found / 201 Created / 400 Bad request
Tip
Elvaco web interface provides a test area for REST API configurations. Go to Configuration and click on Services>REST>HELP>Try to enter the test area.
Use the following table to find out the resources of Elvaco Rest API.
Table 127. List of Rest API resources
|
Service |
Description |
|---|---|
|
/config |
Service for configuring CMe3100, i.e. changing TCP console port, setting e-mail server etc. |
|
/console |
Service for executing console commands. i.e. execute a console command for requesting momentary reports via e-mail. |
|
/datatable |
Service to reach consisting datatables data within the system. |
|
/dbtranslations |
Service for determining database translations, i.e. adding/updating new translations to database. |
|
/device |
Service for handling devices, i.e. M-Bus slaves. |
|
/deviceType |
Service for determining the device types, i.e. electricity, gas, detector, smoke detector etc. |
|
/encryptionkey |
Service for determining encryption keys for M-BUS slaves. |
|
/log |
Service for monitoring log information for different severity levels, i.e. -2 (Debug), -1 (Unknown), 0 (Info), 1 (Warning), 2 (Error), 3 (Critical), 4 (Fatal), 5 (Exception), 6 (Event). |
|
/mdmdata |
Service for reading historical or momentary data from different source. |
|
/mdmserie |
Service for normalized values/meter data from devices. |
|
/mdmseriestemplates |
|
|
/mdmsource |
Service for handling data source for mdmseries, i.e. M-Bus, functions etc. |
|
/mdmtag |
Service for determining tags with related measurementseries. |
|
/operations for unit types |
|
|
/system |
|
|
/unit |
Service for determining units for metering action, i.e. kW, GJ/h, minute(s), day(s) etc. |
|
/user |
Service for determining users and their authentication rights. |
|
/userlink |
Service for determining user links added by the user. |
|
/viewmdmdata |
Service for easier entity which combines mdmdata foreign key with readable data. |
|
/viewmdmserie |
Service for easier entity which combines mdmseries foreign key to readable data. |
Data read from devices are normalized in measurement series. The main parts of measurement series are source, data and series.
The source of a measurement series defines the source of the data, which can be a specific value read from an M-Bus slave. The source can also be used to define mathematical functions to calculate data from one or more measurement series. A measurement series can only have one active source
The data of the measurement series holds information about measurement series' data. By usage of the module; if the data is numeric, data belongs to which measurement series and data source etc. can be monitored.
In this section we will demonstrate a use-case scenario to give better understanding for the usage of the Elvaco Rest API. Below are the steps of scenario, and example responses and requests.
|
Response |
|---|
|
"storageIntervalCron":"", "updateIntervalCron":"", "unitTypeID": 134, "updateOnNewData": false, "description": "Signal strenght in dBm", "expireTimeout": 0, "name": "Signal strenght", "measurementSerieId": 241, "unitId": 58, "apiIdentifier": "61000002-mbus.dib.rf-level.0.0.0.0" "deviceTypeId": "2", "calculationOrder": "0", "createdFromTemplateId": "9", "unitTypeId": 0, "priority": "1",
"storageIntervalCron": "", "updateIntervalCron": "", "unitTypeId": 167, "updateOnNewData": false, "description": "Indoor temperature", "expireTimeout": 0, "name": "Temperature", "measurementSerieId": 242, "unitId": 13, "apiIdentifier": "61000002-mbus.dib.ext-temp.0.0.0.0" "deviceTypeId": "2", "calculationOrder": "0", "createdFromTemplateId": "5", "unitTypeId": 5, "priority": "1",
|
After measurement series information is listed, user can use measurement series id to determine measurement series source.
To be able to get the source information of a measurement series, request with measurement series id as a parameter should be requested.
|
Request |
|---|
|
HTTP GET /Elvaco-Rest/rest/mdmsource/measurementSerieId/{measurementSerieId} HTTP GET /Elvaco-Rest/rest/mdmsource/measurementSerieId/241 |
|
Response |
|---|
|
"sourceType": "mbus", "formatString": null, "constant": 1, "sourceData": "0.mbus.dib.rf-level.0.0.0.0.value", "created": 1418921380184, "measurementSeriesId": 241, "deactivated": -1, "sourceIdentifier": 61000002, "sourceId": 1147
|
As seen on response body below, source type is M-Bus (M-Bus slave) for measurement series with id 241.
Two request examples above let us get mdmserie – measurement series information, and mdmsource – measurement series source information. Now mdmdata – measurement series data information will be listed.
Getting measurement series data can be determined in five different ways with different parameters.
|
Request |
|---|
|
HTTP GET /Elvaco-Rest/rest/mdmdata/all/limit/{limit}/offset/{offset} HTTP GET /Elvaco-Rest/rest/mdmdata/all/limit/100/offset/0 |
Note
Requesting too many mdmdata (measurement series data) entities might create heavy loading on application. Using limit and offset with pagination implementation is suggested for this case.
|
Response |
|---|
|
"total_records": 38728, "limit": 100, "offset": 0, "values": [
"numeric": true, "status": 0, "created": 1418921232000, "value": 62000501, "sourceDate": 1418921230641, "measurementSerieId": 188, "effectiveDate": 1418921220000, "measurementSerieDataId": 204, "valueAsString": "62000501,000", "sourceId": 1094
"numeric": false, "status": 0, "created": 1418921235000, "value": 0, "sourceDate": 1418921230641, "measurementSerieId": 189, "effectiveDate": 1418921220000, "measurementSerieDataId": 205, "valueAsString": "1.6.3", "sourceId": 1095
"numeric": true, "status": 0, "created": 1418921237000, "value": 4, "sourceDate": 1418921230641, "measurementSerieId": 191, "effectiveDate": 1418921220000, "measurementSerieDataId": 207, "valueAsString": "4,000", "sourceId": 1097
|
|
Request |
|---|
|
HTTP GET /ElvacoRest/rest/mdmdata/measurementserieId/{measurementserieId}/limit/{limit}/offset/{offset} HTTP GET /Elvaco-Rest/rest/mdmdata/measurementserieId/241/limit/100/offset/0 |
|
Response |
|---|
|
"total_records": 296, "limit": 100, "offset": 0, "values": [
"numeric": true, "status": 0, "created": 1418921380000, "value": -66, "sourceDate": 1418921374435, "measurementSerieId": 241, "effectiveDate": 1418921340000, "measurementSerieDataId": 257, "valueAsString": "-66,000", "sourceId": 1147
"numeric": true, "status": 0, "created": 1418925604000, "value": -66, "sourceDate": 1418925601121, "measurementSerieId": 241, "effectiveDate": 1418925600000, "measurementSerieDataId": 523, "valueAsString": "-66,000", "sourceId": 1147
|
|
Request |
|---|
|
HTTP GET /ElvacoRest/rest/mdmdata/measurementSerieId/{measurementSerieId}/latest/ {numberofread} HTTP GET /Elvaco-Rest/rest/mdmdata/measurementSerieId/693/latest/5 |
|
Response |
|---|
|
"total_records": 337, "limit": 5, "offset": 0, "values": [
"numeric": false, "status": -1, "created": 1426169671000, "value": 0, "sourceDate": 1426169671682, "measurementSerieId": 693, "effectiveDate": 1426169640000, "measurementSerieDataId": 71619, "valueAsString": "N/A", "sourceId": 1599
"numeric": true, "status": 0, "created": 1426172404000, "value": 0, "sourceDate": 1426169667730, "measurementSerieId": 693, "effectiveDate": 1426172400000, "measurementSerieDataId": 71686, "valueAsString": "0,000", "sourceId": 1599
"numeric": true, "status": 0, "created": 1426176005000, "value": 0, "sourceDate": 1426172401560, "measurementSerieId": 693, "effectiveDate": 1426176000000, "measurementSerieDataId": 71753, "valueAsString": "0,000", "sourceId": 1599
"numeric": true, "status": 0, "created": 1426179605000, "value": 0, "sourceDate": 1426176001513, "measurementSerieId": 693, "effectiveDate": 1426179600000, "measurementSerieDataId": 71820, "valueAsString": "0,000", "sourceId": 1599
"numeric": true, "status": 0, "created": 1426183205000, "value": 0, "sourceDate": 1426179601471, "measurementSerieId": 693, "effectiveDate": 1426183200000, "measurementSerieDataId": 71887, "valueAsString": "0,000", "sourceId": 1599
|
|
Request |
|---|
|
HTTP GET /ElvacoRest/rest/mdmdata/created/{created}/limit/{limit}/offset/{offset} HTTP GET /Elvaco-Rest/rest/mdmdata/created/1420448349000/limit/100/offset/0 |
|
Response |
|---|
|
"total_records": 8, "limit": 100, "offset": 0, "values": [
"numeric": true, "status": 0, "created": 1420448349000, "value": 16.44, "sourceDate": 1420448349043, "measurementSerieId": 188, "effectiveDate": 1420448340000, "measurementSerieDataId": 204, "valueAsString": "16,440", "sourceId": 1094
"numeric": true, "status": 0, "created": 1420448349000, "value": 24.03, "sourceDate": 1420448349043, "measurementSerieId": 189, "effectiveDate": 1420448340000, "measurementSerieDataId": 205, "valueAsString": "24,030", "sourceId": 1095
"numeric": true, "status": 0 "created": 1420448356000, "value": 16.51, "sourceDate": 1420448356214, "measurementSerieId": 190, "effectiveDate": 1420448340000, "measurementSerieDataId": 206, "valueAsString": "16,510", "sourceId": 1096
"numeric": true, "status": 0, "created": 1420448356000, "value": 23.990000000000002, "sourceDate": 1420448356214, "measurementSerieId": 191, "effectiveDate": 1420448340000, "measurementSerieDataId": 207, "valueAsString": "23,990", "sourceId": 1097
"numeric": true, "status": 0, "created": 1420448426000, "value": 16.44, "sourceDate": 1420448349043, "measurementSerieId": 188, "effectiveDate": 1420448400000, "measurementSerieDataId": 208, "valueAsString": "16,440", "sourceId": 1094
"sourceId": 1094 "status": 0, "created": 1420448426000, "value": 24.02, "sourceDate": 1420448425374, "measurementSerieId": 189, "effectiveDate": 1420448400000, "measurementSerieDataId": 209, "valueAsString": "24,020", "sourceId": 1095
"numeric": true, "status": 0, "created": 1420448426000, "value": 16.48, "sourceDate": 1420448425374, "measurementSerieId": 190, "effectiveDate": 1420448400000, "measurementSerieDataId": 210, "valueAsString": "16,480", "sourceId": 1096
"numeric": true, "status": 0, "created": 1420448426000, "value": 23.990000000000002, "sourceDate": 1420448425374, "measurementSerieId": 191, "effectiveDate": 1420448400000, "measurementSerieDataId": 211, "valueAsString": "23,990", "sourceId": 1097
|
The request will return you measurement series data from requested created with limit and offset. Created parameter should be in milliseconds.
|
Request |
|---|
|
HTTP GET /ElvacoRest/rest/mdmdata/effectiveDate/from/{from}/to/{to}/limit/{limit}/offset/{off set} HTTP GET /ElvacoRest/rest/mdmdata/effectiveDate/from/1420448340000/to/1420548400000/limit/100 /offset/0 |
|
Response |
|---|
|
"total_records": 204, "limit": 100, "offset": 0, "values": [
"numeric": true, "status": 0, "created": 1420448349000, "value": 16.44, "sourceDate": 1420448349043, "measurementSerieId": 188, "effectiveDate": 1420448340000, "measurementSerieDataId": 204, "valueAsString": "16,440", "sourceId": 1094
"numeric": true, "status": 0, "created": 1420448426000, "value": 23.990000000000002, "sourceDate": 1420448425374, "measurementSerieId": 191, "effectiveDate": 1420448400000, "measurementSerieDataId": 211, "valueAsString": "23,990", "sourceId": 1097
|
The request will return you measurement series data from requested effective date range with limit and offset. Effective date parameter should be in milliseconds
Comments (0 comments)