Skip to main content
Version: 0.14

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 = 255
  • 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.

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

note

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

  • * matches zero or more characters until a slash character /
  • ** matches zero or more characters
  • ? Matches exactly one character which is not a slash /
  • | or , divides alternative patterns
  • any other character matches itself

Match is case insensitive.

Since if store is populated with enough keys with full value length and non-restrictive match is specified the response can grow too large its size is limited to 2KB. If a response would exceed this limit error is returned.

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

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

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

  • * matches zero or more characters until a slash character /
  • ** matches zero or more characters
  • ? Matches exactly one character which is not a slash /
  • | or , divides alternative patterns
  • any other character matches itself

Match is case insensitive.

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="item1 value"

Response

{
  "etag": "0DWty8HwCB",
  "rev": 2733
}

KVS.Get example​

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

Response

{
  "etag": "0DWty8HwCB",
  "value": "item1 value"
}

KVS.GetMany example​

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

Response

{
  "items": {
    "item1": {
      "etag": "0DWty8HwCB",
      "value": "item1 value"
    },
    "item2": {
      "etag": "0DMHqWL0P0",
      "value": "item2 value"
    }
  }
}

KVS.List example​

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

Response

{
  "keys": {
    "item1": {
      "etag": "0DWty8HwCB"
    },
    "item2": {
      "etag": "0DMHqWL0P0"
    }
  },
  "rev": 2744
}

KVS.Delete example​

http://192.168.33.1/rpc/KVS.Delete?id=1&method="KVS.Delete"&params={"key":"item1"}

Response

{
  "rev": 2739
}