Christopher Vagnetoft
3d5ba64f87
All checks were successful
phpunit / Integration Tests (push) Successful in 10m3s
169 lines
4.1 KiB
Markdown
169 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
$ 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`:
|
|
|
|
```bash
|
|
$ git clone https://dev.noccylabs.info/paramdb/paramdb.git
|
|
$ cd paramdb
|
|
$ composer install
|
|
$ bin/paramdb
|
|
```
|
|
|
|
## Using
|
|
|
|
### Store values
|
|
|
|
```json
|
|
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.
|
|
|
|
```json
|
|
GET /businessinfo
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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`.
|
|
|
|
```json
|
|
GET /businessinfo/all
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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`.
|
|
|
|
```json
|
|
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}`.
|
|
|
|
```json
|
|
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`.
|
|
|
|
```json
|
|
POST /businessinfo/purge
|
|
```
|