Persist Key/Value Store API

This API is in Alpha, pricing and usage limitations to be determined

The Persist API is a simple key/value store service intended to solve your basic data persistence needs for Beep Boop projects. It is not intended to satisfy the needs for a relational or queryable database service; however, many times a simple out of process key/value store is just what you need.

Each Beep Boop project has it's own Persist key space. The API is intentionally simplistic. Both keys and values are strings, and values may be up to 256Kb. Several underlying components of Beep Boop itself rely on Persist including the Beep Boop bot for Slack and the Slapp conversation store. If you are using Javascript, there is a node.js client for Persist.

Expects project based token for authentication as described on the API page.


Set a Value

Sets the value of a key. Replaces an existing value if it exists.

PUT https://beepboophq.com/api/v1/persist/kv/<key>

Payload:

  • value required : value [string]

Example:

{
  "value": "this is the value of the key"
}

Response:

  • 200 if successful
  • 400 malformed request
  • 500 unexpected error

Returns same response as GET:

{
  "key": "this is a key",
  "value": "this is the value of the key",
  "updated": "2016-09-09T23:16:43.970809Z"
}

Get a Value

Returns the value of a key.

GET https://beepboophq.com/api/v1/persist/kv/<key>

Response:

  • 200 if successful
  • 404 if not found
  • 500 unexpected error
{
  "key": "T014EF9ELD208Y1YSG0b8d60cd2bd149bcad698c1a944b6564",
  "value": "1473463003.000165",
  "updated": "2016-09-09T23:16:43.970809Z"
}

The value property is a string up to 256Kb. For example, it may be a serialized JSON object.

Delete a Value

Delete the value of a key.

DELETE `https://beepboophq.com/api/v1/persist/kv/

Response:

  • 200 if successful including if the key is not found
  • 500 unexpected error

List Keys

Returns an array of keys optionally filtered by begins query parameter.

GET https://beepboophq.com/api/v1/persist/kv

Query Params:

  • begins - filter keys beginging with this value (e.g. begins=TU12345 will only return keys beginning with TU12345)

Response:

  • 200 if successful
  • 500 unexpected error
[
  "T024CD8ELD208Y1YSG0b8d60cd2bd149bcad698c1a944b6564",
  "T024CD8ELD208Y1YSG1cecb0cd14414bcdbc236af0ed6138dd",
  "T024CD8ELD208Y1YSG2e201e77ac5244cc9b5e66046c9aaf7e",
  "T024CD8ELD208Y1YSG30e6f29d6b5d463c8620dba3a9639099",
  "T024CD8ELD208Y1YSG3121c2a2a0794ceb9fedd9a65f90305d",
  "T024CD8ELD208Y1YSG317b2b6e4eab40ba97a47c308b468f18",
  "T024CD8ELD208Y1YSG5b580f1dc90647b296af5d28420cd561",
  "T024CD8ELD208Y1YSG7fc5c38b58284e478c6729564e6abcce",
  "T024CD8ELD208Y1YSG9f8bff8912c048c3b22cc105374b3b2c",
  "T024CD8ELD208Y1YSGd47cc05cdfc24918a308a6271c5cfdb0",
  "T024CD8ELD208Y1YSGf7469c7ba37942e6b38c90bde033954a"
]

Multi Get Values

Retrieve multiple values for multiple keys at once. Values will be returned corresponding to the order of the keys provided. If a key is not found, a null value will be returned in it's place.

POST https://beepboophq.com/api/v1/persist/mget

Payload:

  • keys required : array of keys

Sample payload:

{
    "keys": [
        "T014EF9ELD208Y1YSG0b8d60cd2bd149bcad698c1a944b6564",
        "T014EF9ELD208Y1YSG1cecb0cd14414bcdbc236af0ed6138dd",
        "T014EF9ELD208Y1YSG2e201e77ac5244cc9b5e66046c9aaf7e",
        "key-doesnt-exist",
        "T014EF9ELD208Y1YSG3121c2a2a0794ceb9fedd9a65f90305d"
    ]
}

Response:

Returns an array of value objects.

  • 200 if successful
  • 500 unexpected error
[
  {
    "key": "T014EF9ELD208Y1YSG0b8d60cd2bd149bcad698c1a944b6564",
    "value": "1473463003.000165",
    "updated": "2016-09-09T23:16:43.970809Z"
  },
  {
    "key": "T014EF9ELD208Y1YSG1cecb0cd14414bcdbc236af0ed6138dd",
    "value": "1473445200.000122",
    "updated": "2016-09-09T18:20:00.905917Z"
  },
  {
    "key": "T014EF9ELD208Y1YSG2e201e77ac5244cc9b5e66046c9aaf7e",
    "value": "1473447536.000149",
    "updated": "2016-09-09T18:58:57.432933Z"
  },
  null,
  {
    "key": "T014EF9ELD208Y1YSG3121c2a2a0794ceb9fedd9a65f90305d",
    "value": "1473463267.000179",
    "updated": "2016-09-09T23:21:07.544027Z"
  }
]

Persist Node.js Client

For your convenience there is a node.js Javascript client for Persist. Though Persist stores simple strings, this client will automatically JSON.stringify() and JSON.parse() objects passed as values.

If you'd like to see clients in other languages, please let us know.

If running on Beep Boop the below example should just work. If running outside of Beep Boop it will fall back to an in memory store. See further configuration options below in the Github README.

var kv = require('beepboop-persist')()

kv.set('a key', { khaled: 'water', life: 100 }, function (err) {
  // handle error :)
  kv.get('a key', function (err, val) {
    // handle error :)
    // val should be { khaled: 'water', life: 100 }

    var begins = 'ke'
    kv.list(begins, function (err, keys) {
      // handle error :)
      // keys should be []

      kv.list(function (err, keys) {
        // handle error :)
        // keys should be ['a key']
        kv.del('a key', function (err) {
          // handle error :)
          // 'a key' should be deleted
        })
      })
    })
  })
})