Key-value store
Small JSON values with revisions, for user interfaces.
| Operation | Kind | HTTP |
|---|---|---|
kv.list | call | GET /v1/kv/{namespace} |
kv.follow | stream | GET /v1/kv/{namespace} |
kv.get | call | GET /v1/kv/{namespace}/{key} |
kv.set | call | PUT /v1/kv/{namespace}/{key} |
kv.delete | call | DELETE /v1/kv/{namespace}/{key} |
kv.list
The keys of a namespace with their values.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
namespace | path | yes | A namespace |
Result
| Field | Type | Description |
|---|---|---|
entries | KvEntry[] |
{
"id": 1,
"op": "kv.list",
"args": {
"namespace": "ui"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
namespace | path | yes | A namespace. |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
set | JSON | A key was written. Example: {"key":"layout","revision":4,"value":{"columns":3}} |
removed | JSON | A key was removed. Example: {"key":"layout","removed":true} |
dropped | JSON | This follower was too slow. events counts the server's events it missed, of every kind. List the namespace again. Example: {"dropped":{"events":12}} |
{
"id": 1,
"op": "kv.follow",
"args": {
"namespace": "ui"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
namespace | path | yes | A namespace |
key | path | yes | A key |
Result
| Field | Type | Description |
|---|---|---|
key | string | |
revision | integer | |
updated | string | |
value | any |
Errors
| Status | When |
|---|---|
| 404 | No such key |
{
"id": 1,
"op": "kv.get",
"args": {
"namespace": "ui",
"key": "layout"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
namespace | path | yes | A namespace |
key | path | yes | A key |
if_match | header If-Match | no | Write only if the key is at this revision |
if_none_match | header If-None-Match | no | *: write only if the key is new |
Input
The value: any JSON, at most 64 KB
Result
| Field | Type | Description |
|---|---|---|
key | string | |
revision | integer |
Errors
| Status | When |
|---|---|
| 412 | Someone else wrote in between |
| 413 | The value is too large |
{
"id": 1,
"op": "kv.set",
"args": {
"namespace": "ui",
"key": "layout"
},
"data": {
"columns": 2
}
}{
"id": 1,
"result": {
"key": "layout",
"revision": 3
}
}kv.delete
Remove a key.
Needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
namespace | path | yes | A namespace |
key | path | yes | A key |
if_match | header If-Match | no | Remove only if the key is at this revision |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
Errors
| Status | When |
|---|---|
| 404 | No such key |
| 412 | Someone else wrote in between |
{
"id": 1,
"op": "kv.delete",
"args": {
"namespace": "ui",
"key": "layout"
}
}{
"id": 1,
"result": {
"ok": true
}
}Types
The named types used on this page.
KvEntry
| Field | Type | Description |
|---|---|---|
key | string | |
revision | integer | |
updated | string | |
value | any |