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

Token Authentication

Each user with is_staff=True is given a unique API Key Token to interact with the API.

Token Authentication is made for programatical high level access of the API. To make other services use the API via a Token make a sepatate user for them and use the token in all authentications.

Users with Token Authentication access to all actions in the API.

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.

User JWT Auth

Users with is_staff=False are able to request a JSON Web Token (JWT) via the /auth/jwt endpoints.

The JWT endpoint issues a JWT with only read access to the API and will filter all results to the entites the users organization has access to. When using User JWT Auth the organization field of all request bodys an be omittted and if you add it in the request body it will be cleaned and the correct organization ID will be added. For users that are part of several organizations it is possible to switch organization by requesting a new JWT for another organization.

User JWT Auth is used for client applications using the API. Mobile apps, single page application etc.

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

Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

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

WWW-Authenticate: JWT

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.

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.

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.

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.

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.

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.

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.