CMe3100 REST API Plugin

Introduction

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.

Services

List of services

Use the following table to find out the resources of Elvaco Rest API.

Table 128. 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.


Using services

Elvaco Rest API is based on open standards, any web language can be used to access the API. To use Elvaco Rest API, application should make HTTP request and parse the response. Basic authentication required.

Base URL: http://yourserver:port /Elvaco-Rest/rest

REST Services

Access meter data

Data read from devices are normalized in measurement series. The main parts of measurement series are source, data and series.

Source

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

Series

The series defines how data from the source are published to the user or other interface.

Data

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.

Examples

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.

User wants to list all measurement series on the system.

Request

HTTP GET /Elvaco-Rest/rest/mdmserie/all

Response

[

{

"storageIntervalCron": "",

"updateIntervalCron": "",

"unitTypeId": 134,

"updateOnNewData": false,

"description": "Signal strenght in dBm",

"expireTimeout": 0,

"name": "Singal 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.

User wants to get the source of the measurement series.

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.

User wants to get measurement series data.

Getting measurement series data can be determined in five different ways with different parameters.

Listing all measurement series data with limit and offset.

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

}

]

}

Listing measurement series data from specific measurement serie with limit and offset.

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

}

]

}

Listing measurement serie data with latest number of read.

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

}

]

}

Listing measurement series data from when it is created with limit and offset.

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

},

{

"numeric": true,

"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.

Listing measurement series data with effective date from/to with limit and offset.

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

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Article is closed for comments.