Service

Service #

Service object:

Field Type Description
name string Unique name of service
config object Config object
messages object array Array of Message objects

All services #

List all the services for a device:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/services

Service #

Each service is addressed under the device api under the path api/v1/device/<dev_id>/service/<service namespace>.

See Services for available services.

Config #

Config object:

Field Type Description
updated timestamp UTC time of update from API
state string State of configuration sync
value object Config value

Any service config can be addressed on: api/v1/device/<dev_id>/service/<service namespace>/config

Read config object:

curl -H "X-IOTREADY-CONFIG-NEXT-GEN: true" -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config

Schema #

The service config also got a json schema definition: api/v1/device/<dev_id>/service/<service namespace>/config/schema

Read config schema:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config/schema

Value #

Read config value:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config/value

Set config value:

curl -H "X-API-Key: <api key>" -X PUT -d '{"enable":true}' \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config/value

Modify config value according to JSON merge patch (RFC7396:

curl -H "X-API-Key: <api key>" -X PATCH -d '{"enable":true}' \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config/value
Beware that due to the constrains described in Architecture/NB IoT any newly set configuration will be set in the device on next connection interval or on an device event being delivered.

Legacy Config #

Not recommended for new integrations, scheduled for deprecation.

Legacy config object:

Field Type Description
updated timestamp UTC time of update from API
syncstate string State of configuration sync
time timestamp UTC time state change
config object Config value

Read legacy config object:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config

Legacy set config:

curl -H "X-API-Key: <api key>" -X PUT -d '{"enable":true}' \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/config

Datasync #

Datasync are synchronized data sets. These data sets can have different structures:

  • Value array. Key and value is the same.
  • key value. Value can be of different types.
  • BLOB: Single binary data object.

Datasync path: api/v1/device/<dev_id>/service/<service namespace>/datasync

Datasync object:

Field Type Description
name string name of datasync
type string Datasync type. TBD
schema object Datasync data schema
updated timestamp UTC time of latest update via api
items number Number of data items
synced boolean Synchronization state
sync_time timestamp UTC time of synchronization completed
sync_percent number Synchronization percentage
error string Synchronization error message

List all datasyncs:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasyncs

Get single datasync by name:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>

Get datasync schema:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>/schema

Get datasync data:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>/data

Set datasync data:

curl -H "X-API-Key: <api key>" -X PUT \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>/data

Add single datasync item:

curl -H "X-API-Key: <api key>" -X PUT \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>/data/<key>

Remove single datasync item:

curl -H "X-API-Key: <api key>" -X DELETE \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>/data/<key>

Modify #

For array type modify operations there is a vendor specific patch operation supported.

Content-Type: application/vnd.iotready.array-patch+json

Example array patch json object:

{
    "add": [
        "12345678"
    ],
    "remove": [
        "12345678"
    ],
    "strict": false
}

curl -H "X-API-Key: <api key>" -X PATCH \
    -H "Content-Type: application/vnd.iotready.array-patch+json" \
    -d '{"add":["12345678"]}' \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/datasync/<name>/data

JSON Schema for array patch:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Iot Ready Datasync array patch",
    "type": "object",
    "properties": {
        "add": {
            "title": "Add",
            "description": "Add values to array",
            "type": "array"
        },
        "remove": {
            "title": "Remove",
            "description": "Remove values from array",
            "type": "array"
        },
        "strict": {
            "title": "Strict",
            "description": "Strict mode. Fail on adding duplicates or removing not found",
            "type": "boolean",
            "default": false
        }
    }
}

Message #

Message path: api/v1/device/<dev_id>/service/<service namespace>/message

Message object:

Field Type Description
name string name of message
time timestamp UTC time of last message
last object Last message value

List all message objects:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/messages

Get message object by name:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/message/<message name>

Get message value by name:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/123/service/<service namespace>/message/<message name>/last

If there is no last message this will return null.

Legacy last message endpoint #

There is a legacy last message endpoint still supported on api/v1/device/<dev_id>/service/<service namespace>/last/<message name>

Not recommended for new integrations, scheduled for deprecation.