Skip to main content
Version: 1.0

KVS

The KVS (Key-Value Store) service provides a basic persistent storage of key-value pairs. Keys are strings and values can be any valid JSON value. The service is accessed thorugh RPC and the follwoing methods are provided: KVS.Set, KVS.Delete, KVS.Get, KVS.List and KVS.GetMany. Users of the API can use etag-based mechanism to ensure atomicity of updates. The following limits are enforced:

  • Maximum Key Length = 42
  • Maximum Value Length = 253
  • Maximum Number of Keys Stored = 50

Additionally, a global revision number of the store is maintained which is incremented on every update.

KVS.Set​

This method adds a new key-value pair to the store or updates an existing one.

Request​

Parameters:

PropertyTypeDescription

key

string

The key to be added or updated. Required

value

any JSON value

Value for the key. Required

etag

string

Generated hash uniquely identifying the key-value pair. Optional

note
  • When etag is present it should specify the value for existing pair and is checked against the one in the store so that and update is made only if they match.
  • Otherwise the update is rejected meaning that someone has changed the value after the last access.
  • If etag is not present and the key does not exist it is added or if it exists it is updated unconditionally.
  • If etag is present and the key does not exist error is returned.
note

Up to and including version 2.0.0 the KVStore was flawed due to a limitation in the JSON parser ignoring JSON keys containing dots, resulting in such keys being silently dropped on reboot. With version 2.0.1 there is a partial remedy of the situation not allowing KVStore keys with embedded dot altogether.
So currently keys with dot are not supported in the KVStore. Updated version supporting them is planned for a future release.

Response​

Attributes in the result:

PropertyTypeDescription

etag

string

Generated hash of the newly created or updated item

rev

number

Revision of the store (after update)

KVS.Get​

This method returns the value stored and etag for a given key. If the key does not exist error is returned.

Request​

Parameters:

PropertyTypeDescription

key

string

The key to be looked up. Required

Response​

Attributes in the result:

PropertyTypeDescription

etag

string

Generated hash of the requested item

value

any JSON value

The value for the key

KVS.GetMany​

This method returns the full information stored for items in the store based on an optinal key matching parameter.

Request​

Parameters:

PropertyTypeDescription

match

string

Pattern against which keys are matched. default is * which matches all. Optional

offset

number

Index of the list from which to start generating the result Optional

note

If match is specified the keys are matched according to the following rules:

  • * matches zero or more characters
  • ? Matches exactly one character
  • ',' divides alternative patterns
  • any other character matches itself

Match is case insensitive.

Response​

Attributes in the result:

PropertyTypeDescription

items

object

JSON object containing a set of JSON objects whose keys are the keys matched against the requested pattern with properties etag and value for the corresponding key

offset

number

Index of the first entry in the result

total

number

Total number of available entries

KVS.List​

This method returns a list of existing keys and etags based on an optional match parameter.

Request​

Parameters:

PropertyTypeDescription

match

string

Pattern against which keys are matched. default is * which matches all. Optional

note

Same pattern matching rules as for KVS.GetMany.

Response​

Attributes in the result:

PropertyTypeDescription

keys

object

Whose keys are the keys which matched against the requested pattern and the only property of the corresponding etag

rev

number

Current revision of the store

KVS.Delete​

This methods deletes existing key from the store.

Request​

Parameters:

PropertyTypeDescription

key

string

The key to be deleted. Required

etag

string

Generated hash uniquely identifying the key-value pair. Optional

note
  • When etag is present it should specify the value for existing pair and is checked against the one in the store so that the key is deleted only if they match.
  • Otherwise error is returned.
  • If the key does not exist error is returned.

Response​

Attributes in the result:

PropertyTypeDescription

rev

number

Revision of the store (after delete)

Examples​

KVS.Set example​

http://192.168.33.1/rpc/KVS.Set?key="item1"&value="value1"

Response

{
  "etag": "08UD6EJ+gr/TQr/qou+aYFng==",
  "rev": 1
}

KVS.Get example​

http://192.168.33.1/rpc/KVS.Get?key="item1"

Response

{
  "etag": "08UD6EJ+gr/TQr/qou+aYFng==",
  "value": "value1"
}

KVS.GetMany example​

http://192.168.33.1/rpc/KVS.GetMany?match="item*"

Response

{
  "items": [
    {
      "key": "item1",
      "etag": "08UD6EJ+gr/TQr/qou+aYFng==",
      "value": "value1"
    },
    {
      "key": "item2",
      "etag": "08+jWymZ24aYJvhgIHUpLP0g==",
      "value": "value2"
    }
  ],
  "offset": 0,
  "total": 2
}

KVS.List example​

http://192.168.33.1/rpc/KVS.List?match="item?"

Response

{
  "keys": {
    "item1": {
      "etag": "08UD6EJ+gr/TQr/qou+aYFng=="
    },
    "item2": {
      "etag": "08+jWymZ24aYJvhgIHUpLP0g=="
    }
  },
  "rev": 3
}

KVS.Delete example​

http://192.168.33.1/rpc/KVS.Delete?key="item1"

Response

{
  "rev": 4
}