Utilitarian API (1.1.0)

Download OpenAPI specification:Download

Utilitarian API is a software for Multi Utility AMR (Automatic Meter Reading) built by Palmlund Wahlgren Innovative Technology AB and is targeted to utility organisations that require a more open solution for their AMR Operations.

The source for this documentation can be found on github.com. If you find any errors in the documentation or you have suggestions on how to make it better please create an issue on Github.

Introduction

Utilitarian API is a RESTful API that exposes endpoint for AMR Operations.

The common part deals with general aspects of the API.

Under the Metering part all endpoints for the management of Meter Devices and Meter Readings are gathered.

Under the Jobs part all endpoint for managing the pulling meter data and communication to with Meter Devices are gathered. (Ongoing work)

Authentication

Each user is given a unique API Key Token to interact with the API. It is also possible to use basic auth but not recomended.

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Unauthenticated responses that are denied permission will result in an HTTP 401 Unauthorized response with an appropriate WWW-Authenticate header. For example:

WWW-Authenticate: Token

Note: If you are running an instance of Utilitarian API that is accessable over the Internet you need to make sure that the API is only served under https.

Pagination

The Pagination scheme used for Utiltiarian API is a Limit/Offset scheme.

By using a limit indicates the maximum number of items to return and the offset indicates the starting position of the query in relation to the complete set of unpaginated items. This makes for a very extensible pagination scheme where the client have better control of the returned values. In all responses the total count of items in the compleate set of unpaginated items are returned to be able to know where in the set a pagination response is located.

The limit and offset is applied in query parameters like:

GET https://api.example.org/accounts/?limit=100&offset=400

The following example shows a common result set.

{
  "count": 1023
  "next": "https://api.example.org/accounts/?limit=100&offset=500",
  "previous": "https://api.example.org/accounts/?limit=100&offset=300",
  "results": []
}

Note: Having very large result sets can lead to significant performance issues.

Meter Devices

Operations on Meter Devices

Meter Devices

Meter Devices are the entity that represents a physical (or logical) meter deployed in the field. They handle all information about how to communicate with the meter and how to interpret the data from the meter.

meter-devices_list

get /meter-devices
/v1/metering/meter-devices

Returns a list of MeterDevices

query Parameters
name
string
external_system_reference
string
manufacturer_serial
string
dlms_logical_device_name
string
dlms_system_title
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

meter-devices_create

post /meter-devices
/v1/metering/meter-devices

Creates a MeterDevice

Request Body schema: application/json
name
required
string (Unique Name/Identification of Meter) [ 1 .. 50 ] characters
external_system_reference
string (Reference in external systems. Used for export) <= 50 characters Nullable
manufacturer_serial
string (Meter Serial Number from manufacturer) <= 50 characters Nullable
protocol
required
string (The communication protocol used by the meter device)
Enum:"dlms-cosem" "iec62056-21" "i-flag" "mbus" "modbus" "lis-200"
iec62056_21_address
string (Meter Address used for IEC62056-21 communication) <= 8 characters Nullable
dlms_logical_device_name
string (Logical device name used in DLMS Communication) [ 1 .. 32 ] characters Nullable ^[abcdefABCDEF1234567890]*$
dlms_system_title
string (System title of meter used in DLMS communication) [ 1 .. 16 ] characters Nullable ^[abcdefABCDEF1234567890]*$
type
string <uuid> (Type) Nullable
network_interface
string <uuid> (Network interface) Nullable
has_current_transformer
boolean (Meter has a current transformer in its measurement loop)
current_transformer_ratio
integer (Ratio of current transformer) [ -2147483648 .. 2147483647 ]
has_voltage_transformer
boolean (Meter has a voltage transformer in its measurement loop)
voltage_transformer_ratio
integer (Ratio of voltage transformer) [ -2147483648 .. 2147483647 ]
has_disconnector
boolean (Has disconnector)
disconnector_status
integer (Disconnector status) Nullable
Enum:0 1 2

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "network_interface_info": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0,
  • "created_at": "2019-05-06T17:14:18Z",
  • "updated_at": "2019-05-06T17:14:18Z"
}

meter-devices_read

get /meter-devices/{id}
/v1/metering/meter-devices/{id}

Returns a single MeterDevice

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "network_interface_info": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0,
  • "created_at": "2019-05-06T17:14:18Z",
  • "updated_at": "2019-05-06T17:14:18Z"
}

meter-devices_update

put /meter-devices/{id}
/v1/metering/meter-devices/{id}

Updates a single MeterDevice

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device.

Request Body schema: application/json
name
required
string (Unique Name/Identification of Meter) [ 1 .. 50 ] characters
external_system_reference
string (Reference in external systems. Used for export) <= 50 characters Nullable
manufacturer_serial
string (Meter Serial Number from manufacturer) <= 50 characters Nullable
protocol
required
string (The communication protocol used by the meter device)
Enum:"dlms-cosem" "iec62056-21" "i-flag" "mbus" "modbus" "lis-200"
iec62056_21_address
string (Meter Address used for IEC62056-21 communication) <= 8 characters Nullable
dlms_logical_device_name
string (Logical device name used in DLMS Communication) [ 1 .. 32 ] characters Nullable ^[abcdefABCDEF1234567890]*$
dlms_system_title
string (System title of meter used in DLMS communication) [ 1 .. 16 ] characters Nullable ^[abcdefABCDEF1234567890]*$
type
string <uuid> (Type) Nullable
network_interface
string <uuid> (Network interface) Nullable
has_current_transformer
boolean (Meter has a current transformer in its measurement loop)
current_transformer_ratio
integer (Ratio of current transformer) [ -2147483648 .. 2147483647 ]
has_voltage_transformer
boolean (Meter has a voltage transformer in its measurement loop)
voltage_transformer_ratio
integer (Ratio of voltage transformer) [ -2147483648 .. 2147483647 ]
has_disconnector
boolean (Has disconnector)
disconnector_status
integer (Disconnector status) Nullable
Enum:0 1 2

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "network_interface_info": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0,
  • "created_at": "2019-05-06T17:14:18Z",
  • "updated_at": "2019-05-06T17:14:18Z"
}

meter-devices_partial_update

patch /meter-devices/{id}
/v1/metering/meter-devices/{id}

Partially updates a single MeterDevice

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device.

Request Body schema: application/json
name
required
string (Unique Name/Identification of Meter) [ 1 .. 50 ] characters
external_system_reference
string (Reference in external systems. Used for export) <= 50 characters Nullable
manufacturer_serial
string (Meter Serial Number from manufacturer) <= 50 characters Nullable
protocol
required
string (The communication protocol used by the meter device)
Enum:"dlms-cosem" "iec62056-21" "i-flag" "mbus" "modbus" "lis-200"
iec62056_21_address
string (Meter Address used for IEC62056-21 communication) <= 8 characters Nullable
dlms_logical_device_name
string (Logical device name used in DLMS Communication) [ 1 .. 32 ] characters Nullable ^[abcdefABCDEF1234567890]*$
dlms_system_title
string (System title of meter used in DLMS communication) [ 1 .. 16 ] characters Nullable ^[abcdefABCDEF1234567890]*$
type
string <uuid> (Type) Nullable
network_interface
string <uuid> (Network interface) Nullable
has_current_transformer
boolean (Meter has a current transformer in its measurement loop)
current_transformer_ratio
integer (Ratio of current transformer) [ -2147483648 .. 2147483647 ]
has_voltage_transformer
boolean (Meter has a voltage transformer in its measurement loop)
voltage_transformer_ratio
integer (Ratio of voltage transformer) [ -2147483648 .. 2147483647 ]
has_disconnector
boolean (Has disconnector)
disconnector_status
integer (Disconnector status) Nullable
Enum:0 1 2

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "external_system_reference": "string",
  • "manufacturer_serial": "string",
  • "protocol": "dlms-cosem",
  • "iec62056_21_address": "string",
  • "dlms_logical_device_name": "string",
  • "dlms_system_title": "string",
  • "type": "string",
  • "network_interface": "string",
  • "network_interface_info": "string",
  • "has_current_transformer": true,
  • "current_transformer_ratio": -2147483648,
  • "has_voltage_transformer": true,
  • "voltage_transformer_ratio": -2147483648,
  • "has_disconnector": true,
  • "disconnector_status": 0,
  • "created_at": "2019-05-06T17:14:18Z",
  • "updated_at": "2019-05-06T17:14:18Z"
}

meter-devices_delete

delete /meter-devices/{id}
/v1/metering/meter-devices/{id}

Deletes a single MeterDevice

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device.

Responses

204

No Content

Network Interfaces

Operations on Network Interfaces.

Network Interfaces

A NetworkInterface is an object holding information needed for communication to a meter device. You can connect SIM cards to a network interface. Several meter devices can share the same network interface, for example an MBus gateway. It is also possbile for several network interfaces to share the same SIM Card, for example if using the same IP/SIM-card but different devices are under different ports. Then each meter device would have its own network interface specifiying the port but they would all share the same SIM Card to get the IP address.

Some network interfaces only allows for one open connection and when the network interface is used by communication software we want to make sure that no other job is trying to communicate with the meter devcice. This is done by blocking the network interface. When the communication is done the network interface should be unblocked so that other jobs can connect to it.

Tips: The host parameter is only returned in responses and will contain the following data:

  1. FQDN. If a meter has a DNS compliant name attached to it we assume we want to use that firstly
  2. Static IP Address. If no FQDN is set on the meter it will return the static ip address associated with it.
  3. IP of SIM Card. If no static ip address or FQDN is set the meter will return the IP of the SIM Card attached to it.

network-interfaces_list

get /network-interfaces
/v1/metering/network-interfaces

returns list of NetworkInterfaces

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

network-interfaces_create

post /network-interfaces
/v1/metering/network-interfaces

Create a new Network Interface

Request Body schema: application/json
static_ip_address
string (IP Address of meter that is not bound to SIM) non-empty Nullable
fqdn
string (FQDN, if you are using DNS to lookup IP of meters) <= 200 characters Nullable
port
integer (Port used for IP communication) [ 0 .. 2147483647 ] Nullable
sim
string <uuid> (Sim) Nullable
can_block
boolean (It is possible to block the network interface)

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "static_ip_address": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "static_ip_address": "string",
  • "host": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true,
  • "is_blocked": true,
  • "block_time": "2019-05-06T17:14:19Z",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

network-interfaces_read

get /network-interfaces/{id}
/v1/metering/network-interfaces/{id}

Returns a single NetworkInterface

path Parameters
id
required
string <uuid>

A UUID string identifying this network interface.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "static_ip_address": "string",
  • "host": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true,
  • "is_blocked": true,
  • "block_time": "2019-05-06T17:14:19Z",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

network-interfaces_update

put /network-interfaces/{id}
/v1/metering/network-interfaces/{id}

Updates a single Network Interface

path Parameters
id
required
string <uuid>

A UUID string identifying this network interface.

Request Body schema: application/json
static_ip_address
string (IP Address of meter that is not bound to SIM) non-empty Nullable
fqdn
string (FQDN, if you are using DNS to lookup IP of meters) <= 200 characters Nullable
port
integer (Port used for IP communication) [ 0 .. 2147483647 ] Nullable
sim
string <uuid> (Sim) Nullable
can_block
boolean (It is possible to block the network interface)

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "static_ip_address": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "static_ip_address": "string",
  • "host": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true,
  • "is_blocked": true,
  • "block_time": "2019-05-06T17:14:19Z",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

network-interfaces_partial_update

patch /network-interfaces/{id}
/v1/metering/network-interfaces/{id}

Partially updates a single Network Interface

path Parameters
id
required
string <uuid>

A UUID string identifying this network interface.

Request Body schema: application/json
static_ip_address
string (IP Address of meter that is not bound to SIM) non-empty Nullable
fqdn
string (FQDN, if you are using DNS to lookup IP of meters) <= 200 characters Nullable
port
integer (Port used for IP communication) [ 0 .. 2147483647 ] Nullable
sim
string <uuid> (Sim) Nullable
can_block
boolean (It is possible to block the network interface)

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "static_ip_address": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "static_ip_address": "string",
  • "host": "string",
  • "fqdn": "string",
  • "port": 0,
  • "sim": "string",
  • "can_block": true,
  • "is_blocked": true,
  • "block_time": "2019-05-06T17:14:19Z",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

network-interfaces_delete

delete /network-interfaces/{id}
/v1/metering/network-interfaces/{id}

Deletes a single Network Interface

path Parameters
id
required
string <uuid>

A UUID string identifying this network interface.

Responses

204

No Content

SIM Cards

Operations on SIM Cards

SIM Cards

Utilitarian is focused on IP communication with meters. Many meter have internal or external modems that are used for cellular communications. This require a SIM-card. Many SIM-cards in IoT data plans will give a fixed IP. It is possible to store all your SIM cards in Utiltarian and link them to your meter devices for an easy way of finding the IP for a meter device. If you switch a SIM cards in the field you need to switch it in Utilitarian so that the system can find the meter device.

Tips: It is possible to save a link to the managing software, for example Jasper, of the SIM cards. In future Utilitarian UI this will be rendered as an external link to quickly get access to logs and other SIM cards operations that are not in the scope of Utilitarian.

sim-cards_list

get /sim-cards
/v1/metering/sim-cards

Returns a list of SimCards

query Parameters
iccid
string
imsi
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

sim-cards_create

post /sim-cards
/v1/metering/sim-cards

Creates a new SimCard

Request Body schema: application/json
iccid
required
string (ICCID of the SIM) [ 1 .. 20 ] characters ^[0123456789]*$
imsi
required
string (IMSI of the SIM) [ 1 .. 15 ] characters ^[0123456789]*$
ip_address
string (IP Address associated with the SIM) non-empty Nullable
phone_number
string (Telephone number associated with the SIM) [ 1 .. 30 ] characters Nullable
external_system_link
string <uri> (Link to external system for management of the SIM) [ 1 .. 200 ] characters Nullable

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

sim-cards_read

get /sim-cards/{id}
/v1/metering/sim-cards/{id}

Returns a single SimCard

path Parameters
id
required
string <uuid>

A UUID string identifying this sim card.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

sim-cards_update

put /sim-cards/{id}
/v1/metering/sim-cards/{id}

Updates a single SimCard

path Parameters
id
required
string <uuid>

A UUID string identifying this sim card.

Request Body schema: application/json
iccid
required
string (ICCID of the SIM) [ 1 .. 20 ] characters ^[0123456789]*$
imsi
required
string (IMSI of the SIM) [ 1 .. 15 ] characters ^[0123456789]*$
ip_address
string (IP Address associated with the SIM) non-empty Nullable
phone_number
string (Telephone number associated with the SIM) [ 1 .. 30 ] characters Nullable
external_system_link
string <uri> (Link to external system for management of the SIM) [ 1 .. 200 ] characters Nullable

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

sim-cards_partial_update

patch /sim-cards/{id}
/v1/metering/sim-cards/{id}

Partially updates a single SimCard

path Parameters
id
required
string <uuid>

A UUID string identifying this sim card.

Request Body schema: application/json
iccid
required
string (ICCID of the SIM) [ 1 .. 20 ] characters ^[0123456789]*$
imsi
required
string (IMSI of the SIM) [ 1 .. 15 ] characters ^[0123456789]*$
ip_address
string (IP Address associated with the SIM) non-empty Nullable
phone_number
string (Telephone number associated with the SIM) [ 1 .. 30 ] characters Nullable
external_system_link
string <uri> (Link to external system for management of the SIM) [ 1 .. 200 ] characters Nullable

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "iccid": "string",
  • "imsi": "string",
  • "ip_address": "string",
  • "phone_number": "string",
  • "external_system_link": "http://example.com",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

sim-cards_delete

delete /sim-cards/{id}
/v1/metering/sim-cards/{id}

Deletes a single SimCard

path Parameters
id
required
string <uuid>

A UUID string identifying this sim card.

Responses

204

No Content

Meter Device Types

Operations on Meter Device Types

Meter Device Types

It is possible to have a meter that is of same make and model but differently configured. By adding a different meter type we can have a several different setups of the same manufacturer model.

meter-device-types_list

get /meter-device-types
/v1/metering/meter-device-types

Returns a list of MeterDeviceTypess

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

meter-device-types_create

post /meter-device-types
/v1/metering/meter-device-types

Creates a MeterDeviceType

Request Body schema: application/json
name
required
string (Type name of Meter) [ 1 .. 50 ] characters
description
string (Description of Meter Device Type) <= 500 characters
manufacturer
required
string (Manufacturer name) [ 1 .. 100 ] characters
manufacturer_model
required
string (Manufacturer model name) [ 1 .. 50 ] characters
config
string <uuid> (Config) Nullable

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-types_read

get /meter-device-types/{id}
/v1/metering/meter-device-types/{id}

Returns a single MeterDeviceType

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device type.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-types_update

put /meter-device-types/{id}
/v1/metering/meter-device-types/{id}

Updates a single MeterDeviceType

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device type.

Request Body schema: application/json
name
required
string (Type name of Meter) [ 1 .. 50 ] characters
description
string (Description of Meter Device Type) <= 500 characters
manufacturer
required
string (Manufacturer name) [ 1 .. 100 ] characters
manufacturer_model
required
string (Manufacturer model name) [ 1 .. 50 ] characters
config
string <uuid> (Config) Nullable

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-types_partial_update

patch /meter-device-types/{id}
/v1/metering/meter-device-types/{id}

Partially updates a single MeterDeviceType

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device type.

Request Body schema: application/json
name
required
string (Type name of Meter) [ 1 .. 50 ] characters
description
string (Description of Meter Device Type) <= 500 characters
manufacturer
required
string (Manufacturer name) [ 1 .. 100 ] characters
manufacturer_model
required
string (Manufacturer model name) [ 1 .. 50 ] characters
config
string <uuid> (Config) Nullable

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "manufacturer": "string",
  • "manufacturer_model": "string",
  • "config": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-types_delete

delete /meter-device-types/{id}
/v1/metering/meter-device-types/{id}

Deletes a single MeterDeviceType

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device type.

Responses

204

No Content

Meter Device Configs

Operations on Meter Device Configs

Meter Device Configs

A Meter Device Config stores the configurations of a Meter Device Type. As of now this stores mainly what MeteringSeries it has. The metering series list is used to validate if a meter reading from a meter device is allowed to be saved.

The plan later on is have information about what, for example COSEM objects a meter has, or what MBus Vifes etc the meter has. For example can an IDIS complient meter share configuration with other meters of different make. An OMS compliant Mbus meter can also share configuration between different manufacturers.

meter-device-configs_list

get /meter-device-configs
/v1/metering/meter-device-configs

Returns a list of MeterDeviceConfigs

query Parameters
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

meter-device-configs_create

post /meter-device-configs
/v1/metering/meter-device-configs

Creates a MeterDeviceConfig

Request Body schema: application/json
name
required
string (Device Config Name) [ 1 .. 50 ] characters
series
required
Array of string <uuid>

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "series":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "series":
    [
    ],
  • "series_info": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-configs_read

get /meter-device-configs/{id}
/v1/metering/meter-device-configs/{id}

Returns a single MeterDeviceConfig

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device config.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "series":
    [
    ],
  • "series_info": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-configs_update

put /meter-device-configs/{id}
/v1/metering/meter-device-configs/{id}

Updates a single MeterDeviceConfig

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device config.

Request Body schema: application/json
name
required
string (Device Config Name) [ 1 .. 50 ] characters
series
required
Array of string <uuid>

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "series":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "series":
    [
    ],
  • "series_info": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-configs_partial_update

patch /meter-device-configs/{id}
/v1/metering/meter-device-configs/{id}

Partially updates a single MeterDeviceConfig

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device config.

Request Body schema: application/json
name
required
string (Device Config Name) [ 1 .. 50 ] characters
series
required
Array of string <uuid>

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "series":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "series":
    [
    ],
  • "series_info": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-device-configs_delete

delete /meter-device-configs/{id}
/v1/metering/meter-device-configs/{id}

Deletes a single MeterDeviceConfig

path Parameters
id
required
string <uuid>

A UUID string identifying this meter device config.

Responses

204

No Content

Meter Reading Series

Operations on Meter Reading Series

Meter Reading Series

A MeterReadingSeries is used for grouping all meter values that should be viewed as a time series of values. It also adds "metadata" about the series so that it is possible to know more about the values contained in it.

In Utilitarian we aim to use OBIS codes as series identifier but there is nothing preventing the use of any identifier for a series. Simple string values like "energy" and "power" could be used or more complex identifiers like from the CIM standard.

Since we might have electricity meters that have current and voltage transformers in their measurement loops we need to specify if the series is affected by either the current transformer and/or the voltage transformer ratio.

meter-reading-series_list

get /meter-reading-series
/v1/metering/meter-reading-series

Returns a list of MeterReadingSeries

query Parameters
name
string
unit
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

meter-reading-series_create

post /meter-reading-series
/v1/metering/meter-reading-series

Create a MeterReadingSeries

Request Body schema: application/json
name
required
string (Name of the series. Used to group meter readings.) [ 1 .. 50 ] characters
description
string (Description of the series) <= 250 characters
unit
required
string (Unit characters of the series, ex: kWh) [ 1 .. 10 ] characters
unit_description
string (Longer description of unit) [ 1 .. 250 ] characters Nullable
si_multiplier
string <decimal> (Multiplier to get series unit in SI unit.)
affected_by_ct_ratio
boolean (Series is affected by the current transformer of the meter)
affected_by_vt_ratio
boolean (Series is affected by the voltage transformer of the meter)

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true,
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-reading-series_read

get /meter-reading-series/{id}
/v1/metering/meter-reading-series/{id}

Returns a single MeterReadingSeries

path Parameters
id
required
string <uuid>

A UUID string identifying this meter reading series.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true,
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-reading-series_update

put /meter-reading-series/{id}
/v1/metering/meter-reading-series/{id}

Updates a single MeterReadingSeries

path Parameters
id
required
string <uuid>

A UUID string identifying this meter reading series.

Request Body schema: application/json
name
required
string (Name of the series. Used to group meter readings.) [ 1 .. 50 ] characters
description
string (Description of the series) <= 250 characters
unit
required
string (Unit characters of the series, ex: kWh) [ 1 .. 10 ] characters
unit_description
string (Longer description of unit) [ 1 .. 250 ] characters Nullable
si_multiplier
string <decimal> (Multiplier to get series unit in SI unit.)
affected_by_ct_ratio
boolean (Series is affected by the current transformer of the meter)
affected_by_vt_ratio
boolean (Series is affected by the voltage transformer of the meter)

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true,
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-reading-series_partial_update

patch /meter-reading-series/{id}
/v1/metering/meter-reading-series/{id}

Partially updates a single MeterReadingSeries

path Parameters
id
required
string <uuid>

A UUID string identifying this meter reading series.

Request Body schema: application/json
name
required
string (Name of the series. Used to group meter readings.) [ 1 .. 50 ] characters
description
string (Description of the series) <= 250 characters
unit
required
string (Unit characters of the series, ex: kWh) [ 1 .. 10 ] characters
unit_description
string (Longer description of unit) [ 1 .. 250 ] characters Nullable
si_multiplier
string <decimal> (Multiplier to get series unit in SI unit.)
affected_by_ct_ratio
boolean (Series is affected by the current transformer of the meter)
affected_by_vt_ratio
boolean (Series is affected by the voltage transformer of the meter)

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "unit": "string",
  • "unit_description": "string",
  • "si_multiplier": "string",
  • "affected_by_ct_ratio": true,
  • "affected_by_vt_ratio": true,
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-reading-series_delete

delete /meter-reading-series/{id}
/v1/metering/meter-reading-series/{id}

Deletes a single MeterReadingsSeries

path Parameters
id
required
string <uuid>

A UUID string identifying this meter reading series.

Responses

204

No Content

Meter Readings

Operations on Meter Readings

Meter Readings

Meter Readings are the raw data we receive from meter devices. They are limited to numerical data. Meter Readings table is designed for short term storage of meter values.

meter-readings_list

get /meter-readings
/v1/metering/meter-readings

Returns a list of MeterReadings. Supply both meter_id and series_id in query parameters to get a complete series. Returns a list of only values and timestamps. If the series and meter is omitted the values will be mixed.

query Parameters
meter_device
string
series
string
start_time
string
end_time
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{}

meter-readings_create

post /meter-readings
/v1/metering/meter-readings

Creates a MeterReading

Request Body schema: application/json
meter_device
required
string <uuid> (Meter device)
series
required
string <uuid> (Series)
timestamp
required
string <date-time> (Time when the reading was registered in the meter.)
value
required
string <decimal> (Value of the reading)

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "meter_device": "string",
  • "series": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device": "string",
  • "series": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string",
  • "created_at": "2019-05-06T17:14:19Z"
}

meter-readings_read

get /meter-readings/{id}
/v1/metering/meter-readings/{id}

Returns a single MeterReading

path Parameters
id
required
integer

A unique integer value identifying this meter reading.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device": "string",
  • "series": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string",
  • "created_at": "2019-05-06T17:14:19Z"
}

meter-readings_delete

delete /meter-readings/{id}
/v1/metering/meter-readings/{id}

Deletes a single MeterReading

path Parameters
id
required
integer

A unique integer value identifying this meter reading.

Responses

204

No Content

Staged Meter Readings

Operations on Staged Meter Readings

Staged Meter Readings

Staged Meter Readings are meter readings that when they where received by Utilitarian API did not have a corresponding meter. This might be due to that the meter was set up in the field but was not yet set up in Utilitarian API. To avoid loosing values we save the meter readings for a while and whenever a new meter device is created we will save all staged meter readings as normal meter readings. We also clear the staging table of old values after a set amount of time to make sure the list doesn't grow to large.

staged-meter-readings_list

get /staged-meter-readings
/v1/metering/staged-meter-readings

Returns list of Staged Meter Readings

query Parameters
meter_device_name
string
start_time
string
end_time
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

staged-meter-readings_create

post /staged-meter-readings
/v1/metering/staged-meter-readings

Create a new Staged Meter Readings

Request Body schema: application/json
meter_device_name
required
string (Name of Meter Device) [ 1 .. 50 ] characters
series_name
required
string (Name of Meter Reading Series) [ 1 .. 50 ] characters
timestamp
required
string <date-time> (Time when the reading was registered in the meter.)
value
required
string <decimal> (Value of the reading)

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

staged-meter-readings_read

get /staged-meter-readings/{id}
/v1/metering/staged-meter-readings/{id}

Returns a single Staged Meter Reading

path Parameters
id
required
integer

A unique integer value identifying this staged meter reading.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

staged-meter-readings_update

put /staged-meter-readings/{id}
/v1/metering/staged-meter-readings/{id}

Updates a single Staged Meter Reading

path Parameters
id
required
integer

A unique integer value identifying this staged meter reading.

Request Body schema: application/json
meter_device_name
required
string (Name of Meter Device) [ 1 .. 50 ] characters
series_name
required
string (Name of Meter Reading Series) [ 1 .. 50 ] characters
timestamp
required
string <date-time> (Time when the reading was registered in the meter.)
value
required
string <decimal> (Value of the reading)

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

staged-meter-readings_partial_update

patch /staged-meter-readings/{id}
/v1/metering/staged-meter-readings/{id}

Partially updates a single Staged Meter Reading

path Parameters
id
required
integer

A unique integer value identifying this staged meter reading.

Request Body schema: application/json
meter_device_name
required
string (Name of Meter Device) [ 1 .. 50 ] characters
series_name
required
string (Name of Meter Reading Series) [ 1 .. 50 ] characters
timestamp
required
string <date-time> (Time when the reading was registered in the meter.)
value
required
string <decimal> (Value of the reading)

Responses

200

OK

Request samples

application/json
Copy
Expand all Collapse all
{
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device_name": "string",
  • "series_name": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "value": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

staged-meter-readings_delete

delete /staged-meter-readings/{id}
/v1/metering/staged-meter-readings/{id}

Deletes a single Staged Meter Reading

path Parameters
id
required
integer

A unique integer value identifying this staged meter reading.

Responses

204

No Content

New Meter Readings

Operation on new meter readings

New Meter Readings

This enpoint is used by the different distributed AMR services that send data. It is not always knows by the external service what the database ID is for meter device or meter readings series. This endpoint will do lookups based on the names of the meter device and meter reading series.

new-meter-readings_create

post /new-meter-readings
/v1/metering/new-meter-readings

Receives Meter Readings, single and in list and will send them to background workers for processing.

Responses

201

Created

Meter System Events

Operations on Meter System Events

Meter System Events

A MeterSystemEvent is some form of event occurring in a MeterDevice. It could be an indication that something is wrong (Alarm) or an just a log entry that the meter switched to summer time.

meter-system-events_list

get /meter-system-events
/v1/metering/meter-system-events

Returns a list of MeterSystemEvents

query Parameters
meter_device
string
start_time
string
end_time
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

meter-system-events_create

post /meter-system-events
/v1/metering/meter-system-events

Creates a MeterSystemEvents

Request Body schema: application/json
meter_device
required
string <uuid> (Meter device)
timestamp
required
string <date-time> (Timestamp)
title
required
string (Title of the event) [ 1 .. 50 ] characters
content
required
string (Additional information about the meter system event.) [ 1 .. 500 ] characters

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "meter_device": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "title": "string",
  • "content": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "title": "string",
  • "content": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-system-events_read

get /meter-system-events/{id}
/v1/metering/meter-system-events/{id}

Returns a single MeterSystemEvent

path Parameters
id
required
integer

A unique integer value identifying this meter system event.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "meter_device": "string",
  • "timestamp": "2019-05-06T17:14:19Z",
  • "title": "string",
  • "content": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-system-events_delete

delete /meter-system-events/{id}
/v1/metering/meter-system-events/{id}

Deletes a single MeterSystemEvent

path Parameters
id
required
integer

A unique integer value identifying this meter system event.

Responses

204

No Content

Meter Security Key Collections

Operations on Meter Security Key Collection

Meter Security Key Collection

A Meter Security Key Collection holds all passwords, secrets and encryption keys for a meter device.

The dlms_master_key will never be returned in any of the responses for security reasons.

Note: DLMS Keys are stored in hexadecimal strings. 128 bit key = 32 hex characters, 256 bit key = 64 hex characters.

meter-security-keys_list

get /meter-security-keys
/v1/metering/meter-security-keys

Returns list of MeterSecurityCollections

query Parameters
meter
string
meter_name
string
meter_external_system_reference
string
meter_manufacturer_serial
string
meter_dlms_system_title
string
meter_dlms_logical_device_name
string
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "previous": "http://example.com",
  • "results":
    [
    ]
}

meter-security-keys_create

post /meter-security-keys
/v1/metering/meter-security-keys

Creates a MeterSecurityKeyCollection

Request Body schema: application/json
meter
required
string <uuid> (Meter)
iec62056_21_password
string (Password for use in IEC 62056-21 communication) [ 1 .. 8 ] characters Nullable
dlms_global_unicast_encryption_key
required
string (Global Unicast Encryption Key, GUEK) [ 1 .. 64 ] characters ^[abcdefABCDEF1234567890]*$
dlms_global_broadcast_encryption_key
required
string (Global Broadcast Encryption Key, GBEK) [ 1 .. 64 ] characters ^[abcdefABCDEF1234567890]*$
dlms_master_key
required
string (Master Key or Key Encrypting Key, KEK) [ 1 .. 64 ] characters ^[abcdefABCDEF1234567890]*$
dlms_global_authentication_key
required
string (Global Authentication Key, GAK) [ 1 .. 64 ] characters ^[abcdefABCDEF1234567890]*$

Responses

201

Created

Request samples

application/json
Copy
Expand all Collapse all
{
  • "meter": "string",
  • "iec62056_21_password": "string",
  • "dlms_global_unicast_encryption_key": "string",
  • "dlms_global_broadcast_encryption_key": "string",
  • "dlms_master_key": "string",
  • "dlms_global_authentication_key": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "meter": "string",
  • "iec62056_21_password": "string",
  • "dlms_global_unicast_encryption_key": "string",
  • "dlms_global_broadcast_encryption_key": "string",
  • "dlms_master_key": "string",
  • "dlms_global_authentication_key": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z"
}

meter-security-keys_read

get /meter-security-keys/{id}
/v1/metering/meter-security-keys/{id}

Returns a single MeterSecurityKeyCollection

path Parameters
id
required
string <uuid>

A UUID string identifying this meter security key collection.

Responses

200

OK

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "created_at": "2019-05-06T17:14:19Z",
  • "updated_at": "2019-05-06T17:14:19Z",
  • "iec62056_21_password": "string",
  • "dlms_global_unicast_encryption_key": "string",
  • "dlms_global_broadcast_encryption_key": "string",
  • "dlms_global_authentication_key": "string",
  • "meter":
    {
    }
}

meter-security-keys_delete

delete /meter-security-keys/{id}
/v1/metering/meter-security-keys/{id}

Deletes a single MeterSecurityKeyCollection

path Parameters
id
required
string <uuid>

A UUID string identifying this meter security key collection.

Responses

204

No Content