Skip to content

PertsistentStore API

Version: 1.0.0

Status: ⚫⚪⚪

PersistentStore interface for Thunder framework.

(Defined by PersistentStore.json)

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the PersistentStore interface (version 1.0.0). It includes detailed specification about its methods provided and notifications sent.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

Persistent Store JSON-RPC interface.

Methods

The following methods are provided by the PersistentStore interface:

PersistentStore interface methods:

Method Description
deleteKey Deletes a key from the specified namespace
deleteNamespace Deletes the specified namespace
flushCache Flushes the device cache
getKeys Returns the keys that are stored in the specified namespace
getNamespaces Returns the namespaces
getStorageSizes Returns the size occupied by each namespace
getValue Returns the value of a key from the specified namespace
setValue Sets the value of a key in the the specified namespace
setNamespaceStorageLimit Sets the storage limit for a given namespace
getNamespaceStorageLimit Returns the storage limit for a given namespace

deleteKey method

Deletes a key from the specified namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params.key string mandatory Key
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.success boolean mandatory Legacy parameter (always true) (default: True)

Errors

Message Description
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.deleteKey",
  "params": {
    "namespace": "ns1",
    "key": "key1",
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "success": true
  }
}

deleteNamespace method

Deletes the specified namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.success boolean mandatory Legacy parameter (always true) (default: True)

Errors

Message Description
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.deleteNamespace",
  "params": {
    "namespace": "ns1",
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "success": true
  }
}

flushCache method

Flushes the device cache.

Parameters

This method takes no parameters.

Result

Name Type M/O Description
result object mandatory ...
result.success boolean mandatory Legacy parameter (always true) (default: True)

Errors

Message Description
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.flushCache"
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "success": true
  }
}

getKeys method

Returns the keys that are stored in the specified namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.keys array mandatory ...
result.keys[#] string mandatory Key
result.success boolean mandatory Legacy parameter (always true) (default: True)

Errors

Message Description
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getKeys",
  "params": {
    "namespace": "ns1",
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "keys": [
      "key1"
    ],
    "success": true
  }
}

getNamespaces method

Returns the namespaces.

Parameters

Name Type M/O Description
params object mandatory ...
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.namespaces array mandatory ...
result.namespaces[#] string mandatory Namespace
result.success boolean mandatory Legacy parameter (always true) (default: True)

Errors

Message Description
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getNamespaces",
  "params": {
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "namespaces": [
      "ns1"
    ],
    "success": true
  }
}

getStorageSizes method

Returns the size occupied by each namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.storageList array mandatory ...
result.storageList[#] object mandatory ...
result.storageList[#].namespace string mandatory Namespace
result.storageList[#].size integer mandatory Size in bytes

Errors

Message Description
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getStorageSizes",
  "params": {
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "storageList": [
      {
        "namespace": "ns1",
        "size": 100
      }
    ]
  }
}

getValue method

Returns the value of a key from the specified namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params.key string mandatory Key
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.value string mandatory Value
result.success boolean mandatory Legacy parameter (always true) (default: True)
result?.ttl integer optional Time in seconds

Errors

Message Description
ERROR_PENDING_CONDITIONS Time is not synced
ERROR_NOT_EXIST Unknown namespace
ERROR_UNKNOWN_KEY Unknown key
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getValue",
  "params": {
    "namespace": "ns1",
    "key": "key1",
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "value": "value1",
    "success": true,
    "ttl": 100
  }
}

setValue method

Sets the value of a key in the the specified namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params.key string mandatory Key
params.value string mandatory Value
params?.scope string optional Scope (must be one of the following: account, device) (default: device)
params?.ttl integer optional Time in seconds

Result

Name Type M/O Description
result object mandatory ...
result.success boolean mandatory Legacy parameter (always true) (default: True)

Errors

Message Description
ERROR_PENDING_CONDITIONS Time is not synced
ERROR_INVALID_INPUT_LENGTH Empty/too large namespace or key, or the storage doesn't have enough space
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.setValue",
  "params": {
    "namespace": "ns1",
    "key": "key1",
    "value": "value1",
    "scope": "device",
    "ttl": 100
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "success": true
  }
}

setNamespaceStorageLimit method

Sets the storage limit for a given namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params.storageLimit integer mandatory Size in bytes
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_INVALID_INPUT_LENGTH Empty/too large namespace, or the storage doesn't have enough space
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.setNamespaceStorageLimit",
  "params": {
    "namespace": "ns1",
    "storageLimit": 100,
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

getNamespaceStorageLimit method

Returns the storage limit for a given namespace.

Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params?.scope string optional Scope (must be one of the following: account, device) (default: device)

Result

Name Type M/O Description
result object mandatory ...
result.storageLimit integer mandatory Size in bytes

Errors

Message Description
ERROR_NOT_EXIST Unknown namespace
ERROR_GENERAL Unknown error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getNamespaceStorageLimit",
  "params": {
    "namespace": "ns1",
    "scope": "device"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "storageLimit": 100
  }
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the PersistentStore interface:

PersistentStore interface events:

Notification Description
onValueChanged Triggered whenever any of the values stored are changed using setValue

onValueChanged notification

Triggered whenever any of the values stored are changed using setValue.

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.namespace string mandatory Namespace
params.key string mandatory Key
params.value string mandatory Value
params.scope string mandatory Scope (must be one of the following: account, device) (default: device)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "onValueChanged",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.onValueChanged",
  "params": {
    "namespace": "ns1",
    "key": "key1",
    "value": "value1",
    "scope": "device"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.onValueChanged.