Skip to Content

Key-value store

Small JSON values with revisions, for user interfaces.

OperationKindHTTP
kv.listcallGET /v1/kv/{namespace}
kv.followstreamGET /v1/kv/{namespace}
kv.getcallGET /v1/kv/{namespace}/{key}
kv.setcallPUT /v1/kv/{namespace}/{key}
kv.deletecallDELETE /v1/kv/{namespace}/{key}

kv.list

The keys of a namespace with their values.

Needs the role view.

Arguments

NameWhereRequiredDescription
namespacepathyesA namespace

Result

FieldTypeDescription
entriesKvEntry[]
Request
{
  "id": 1,
  "op": "kv.list",
  "args": {
    "namespace": "ui"
  }
}
Reply
{
  "id": 1,
  "result": {
    "entries": [
      {
        "key": "layout",
        "revision": 3,
        "updated": "text",
        "value": {
          "columns": 2
        }
      }
    ]
  }
}

kv.follow

Changes to a namespace of the key-value store.

A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Needs the role view.

Arguments

NameWhereRequiredDescription
namespacepathyesA namespace.

Frames from the server

FrameKindDescription
setJSONA key was written. Example: {"key":"layout","revision":4,"value":{"columns":3}}
removedJSONA key was removed. Example: {"key":"layout","removed":true}
droppedJSONThis follower was too slow. events counts the server's events it missed, of every kind. List the namespace again. Example: {"dropped":{"events":12}}
Request
{
  "id": 1,
  "op": "kv.follow",
  "args": {
    "namespace": "ui"
  }
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "key": "layout",
    "revision": 4,
    "value": {
      "columns": 3
    }
  }
}

End the subscription with {"sub": 1, "end": true}.

kv.get

One key's value and revision.

Needs the role view.

Arguments

NameWhereRequiredDescription
namespacepathyesA namespace
keypathyesA key

Result

FieldTypeDescription
keystring
revisioninteger
updatedstring
valueany

Errors

StatusWhen
404No such key
Request
{
  "id": 1,
  "op": "kv.get",
  "args": {
    "namespace": "ui",
    "key": "layout"
  }
}
Reply
{
  "id": 1,
  "result": {
    "key": "layout",
    "revision": 3,
    "updated": "text",
    "value": {
      "columns": 2
    }
  }
}

kv.set

Write a key, optionally only if nobody wrote in between.

Needs the role operate.

Arguments

NameWhereRequiredDescription
namespacepathyesA namespace
keypathyesA key
if_matchheader If-MatchnoWrite only if the key is at this revision
if_none_matchheader If-None-Matchno*: write only if the key is new

Input

The value: any JSON, at most 64 KB

Result

FieldTypeDescription
keystring
revisioninteger

Errors

StatusWhen
412Someone else wrote in between
413The value is too large
Request
{
  "id": 1,
  "op": "kv.set",
  "args": {
    "namespace": "ui",
    "key": "layout"
  },
  "data": {
    "columns": 2
  }
}
Reply
{
  "id": 1,
  "result": {
    "key": "layout",
    "revision": 3
  }
}

kv.delete

Remove a key.

Needs the role operate.

Arguments

NameWhereRequiredDescription
namespacepathyesA namespace
keypathyesA key
if_matchheader If-MatchnoRemove only if the key is at this revision

Result

FieldTypeDescription
okboolean

Errors

StatusWhen
404No such key
412Someone else wrote in between
Request
{
  "id": 1,
  "op": "kv.delete",
  "args": {
    "namespace": "ui",
    "key": "layout"
  }
}
Reply
{
  "id": 1,
  "result": {
    "ok": true
  }
}

Types

The named types used on this page.

KvEntry

FieldTypeDescription
keystring
revisioninteger
updatedstring
valueany

On this page