Skip to content

Conventions

Requests

All payloads (request and response body) are:

  • Valid JSON i.e. Double-quotes for all property name and string values.
  • Strict camelCase is used for all attribute names (with the exception of energy data, see below).
  • Uppercase attribute names use strict camelCase rules: e.g. SIM ID > simId, IMSI > imsi. (with the exception of energy data, see below)
  • Energy data only: for backwards compatibility with implementations against the v2 API, we retain the energy data capitalisation of attribute names. For example, vRMS, iRMSMin which don't conform to strict camelCase rules (which would be vrms, irmsMin for these examples) etc.

All endpoints accept and return Content-Type: application/json.

All requests MUST include the Authorization: Bearer {api-key} header.

Device naming conventions

Device ID is a synonym for "serial number." It is always uppercase, with no spaces or other punctuation, e.g. D123456789012.

IDs for sub-entities of the device (such as Channels and Switches) use an underscore separator followed by a single character (e.g. 'C' for channel or 'S' for switch) followed by a one-indexed (not zero-indexed) ID. For example, for device D123456789012 the first switch would be D123456789012_S1 and the 3rd channel would be D123456789012_C3.

IDs for Device, Channel and Switch are also always uppercase.

Why?

  • Sub-entity IDs are one-indexed to match common language used to describe channels in a device i.e. people say "channel 1" not "channel zero".
  • The underscore is used to enable usage as a property/attribute in common programming languages, such as Javascript or python (e.g. myDevice.switches.D123456789012_S1).

Write HTTP methods

The PUT method is not supported (even where it might be applicable) as the same function can be achieved with using PATCH and providing all values for an object. To simplify the API, we only support PATCH.

Where applicable, a POST method called on an existing resource will update the existing resource as though PATCH had been called, and will not return an HTTP error status for incorrect use of the POST method.

Where read-only properties are provided in an object passed to the API in a POST or PATCH operation, those properties will be ignored, rather than raising an error. This enables the flow "retrieve data > modify data > PATCH data" without having to prune the object first. For example, if you provide a different device.comms.imsi value in the PATCH /devices/{device-id} API call, the device.comms.imsi property value will not be updated, but will also not raise an HTTP status error (assuming other provided and writable values are valid).

Payload content

We are likely to add new fields to payloads over time. Ensure that your implementing code will not break if a new field is added.

Where a value can contain an empty value, the API will typically not return the attribute at all, rather than the attribute with a null or empty object {} response.

Empty values

At times, some fields may not be returned in response to context (e.g. certain device status fields may not be returned for uninitialised devices).

As a general guide, if a property has no value it is omitted rather than specified with a null or empty value.

However, there are exceptions. For example:

  • if null is a valid value indicating a specific state (e.g. "not set")
  • an empty data set is a valid value that holds semantic value. Such is the case for an energy data query where no energy data has been recorded for that period. An empty value indicates "no data for period" in contrast to a 204 No Data response which indicates no energy data for the device.

Thus, it is important to always "code defensively" by checking for the existence of an attribute/property before accessing it (if doing so would result in an error).