ParamDB

ParamDB is a key-value store that is time-aware. Multiple values can be assigned to each key with unique validity ranges. It can be used to feed static information that varies with time to templates or to serve news.

Introduction

There are situations where you need data to slap into a template, and the data may vary over time.

• Sending alert e-mails including contact information for the curent support techs.
• Seasonal greetings or out-of-office notices in automatically generated content.

ParamDB solves this problem by serving collections of keys over HTTP. A collection can contain any number of keys, and a key can contain any number of values. As the values are serialized, ParamDB could be used to serve arrays or JSON objects representing work schedules, service configuration, or any other clever use you can think of.

Caution

You can put a lot of data into a collection, both structured and ustructured. But you don't want to put too much as every key of the collection is matched and returned when the collection is queried.

Features

• Virtually unlimited collections with virtually unlimited keys.
• Every key can have any number of values with a validity range, and a fallback key without a validity range for when no range matches.
• Values are serialized, so arrays and objects are okay to use.
• Not intended to be running as a public service, so there is no authentication, for now.

Future

• Metadata; store with key "meta" in value set post call, returned under a "meta" key in the result list.

Installing

It is recommended to run ParamDB using docker:

$ docker run -v $PWD/var:/application/var -p 8000:8000 \
    --name paramdb \
    dev.noccylabs.info/paramdb/paramdb:latest

You can also clone and install the repository using composer:

$ git clone https://dev.noccylabs.info/paramdb/paramdb.git
$ cd paramdb
$ composer install
$ bin/paramdb

Using

Store values

POST /businessinfo
Content-Type: application/json

[
  {
    "key": "openhours",
    "value": "Mo-Fr 09-17, Sa-Su 12-02",
    "valid": {
      "from": "2024-10-01 00:00:00 +02:00",
      "until": "2024-10-07 23:59:59 +02:00"
    }
  }
]

Note

The only required keys are key and value. As there can only be one value without validity it will overwrite, any request without validity will overwrite any existing value without a specified validity.

Retrieve current values

Retrieve all current values by getting /{collection}. If all values in a key have a validity span and none matches, they key will not be included in the response.

GET /businessinfo

{
  "openhours": "Mo-Fr 09-17, Sa-Su 10-01"
}

Query params:

• date= - override date (default is now) in the format "Y-m-d H:i:s P"

Retrieve all values

Retrieve all keys and values, together with the value IDs by getting /{collection}/all.

GET /businessinfo/all

{
  "openhours": [
    {
      "id": 13,
      "value": "Mo-Fr 09-17, Sa-Su 10-01"
    },
    {
      "id": 19,
      "value": "Mo-Fr 09-17, Sa-Su 12-02",
      "valid": {
        "from": "2024-10-01 00:00:00 +02:00",
        "until": "2024-10-07 23:59:59 +02:00"
      }
    ]
  }
}

Query params:

• only= - comma-separated list of keys to match

Delete value

Delete by posting an array of value IDs and keys to delete to /{collection}/delete.

POST /businessinfo/delete
Content-Type: application/json

[ 19, "some.key" ]

Update a value

Update by including an existing id with the set request posted to /{collection}.

POST /businessinfo
Content-Type: application/json

{
  "openhours": {
    "id": 19,
    "value": "Mo-Fr 09-17, Sa-Su 12-03",
    "valid": {
      "from": "2024-10-01 00:00:00 +02:00",
      "until": "2024-10-07 23:59:59 +02:00"
    }
  }
}

Delete a colleciton

Purge a collection by posting to /{collection}/purge.

POST /businessinfo/purge