dcache

dcache is a PHP REST API implementing a JSON data cache.

The data cache consists of data sets containing multiple properties as key-value-pairs.
A data set is identified by an unique token.
Data Provider can create, update, and remove data sets.
Consumer can query a data set identified by the provided token.

A running demo is available at: https://dcache.schademarmelade.de/.

Usage examples:

Selected Home Assistant entities can be pushed to dcache and visualized on a TRMNL e-ink display via a custom TRMNL-Plugin.
The result status of a DevOps build pipeline can be sent to dcache and visualized on a WLED led strip.
The battery status of multiple IoT devices is available in a single dcache data set.
...

A typical data flow between Home Assistant, dcache, and TRMNL could look like this:

HA provides temperature=25
HA provides humidity=65
TRMNL receives { temperature=25, humidity=65 }
HA provides fan=on
HA provides humidity=40
TRMNL receives { temperature=25, humidity=40, fan=on }

Server Setup

Simply upload the www folder to your PHP enabled webserver and open the related address in a browser to setup your database connection.

Development Setup

Local development on Windows requires the following setup:

Install Git, NodeJs and VSCode.
Clone the GitHub repo https://github.com/ramdacxp/dcache in VSCode.
Open the created local folder in VSCode and confirm the installation of all recommended extensions.
Install PHP and MariaDB locally into a bin subfolder by executing npm install.
Import database test data via reset-testdata.cmd.

The installation can be repeated by executing the related install-xxx.cmd batch files. No system wide settings are modified during the installation.

The database content can be reset to the initial test data with reset-testdata.cmd. Already existing data in dcache tables will be removed!

All tools and test data can be removed completely by deleting the bin and node_modules sub-folders.

Run dcache locally

Execute npm start or choose Terminal > Run Build Task... in VSCode.
Open the local dev webserver address http://localhost:8080/ in your browser.
Stop the servers by pressing Ctrl-C in the Terminal window.

Settings

If the settings file src/settings.php is missing, a settings form is shown on the website to interactively configure the database connection. Simply accept the default values if using the development servers. Once configured, the form is no longer available. To revert the configuration, the settings file src/settings.php needs to be removed.

The default src/settings.php will have the following content:

<?php
$settings = [];
$settings["database"] = "mysql:host=localhost;dbname=dcache";
$settings["user"] = "root";
$settings["password"] = "";
$settings["prefix"] = "dc-";

API Details

The REST API is exposed at /api.php.

For a list of supported requests and related responses, please refer to the requests.http sample file. All requests can be executed against the provided PHP development webserver in order to test and debug the API. This requires VSCode with the REST Client extension installed.

Method	URL	Description	Success Response
GET	`/api.php?token=T`	Query complete dataset `T`	Dataset `T` as object `{...}`
GET	`/api.php?token=T&property=P`	Query property `P` from dataset `T`	Value of `P` as string `"val"`
GET²	`/api.php?token=T&property=P&value=V`	Update property `P` to `V` in dataset `T`	Updated dataset `T` as object `{...}`
POST	`/api.php?token=T`	Update provided properties in dataset `T`	Updated dataset `T` as object `{...}`
DELETE	`/api.php?token=T`	Remove complete dataset `T`	Boolean `true`
DELETE	`/api.php?token=T&property=P`	Remove property `P` from dataset `T`	Boolean `true`
GET³	`/api.php?method=delete&token=T`	Remove complete dataset `T`	Boolean `true`
GET³	`/api.php?method=delete&token=T&property=P`	Remove property `P` from dataset `T`	Boolean `true`

Additional GET methods as available to use the complete REST API from a regular web browser:
² - This GET method behaves like a POST of the single property P.
³ - With the parameter method=delete the DELETE requests can be invoked via GET.

Restrictions

Type	Length	Characters
Dataset token `T`	min. `8`	`a-z`, `A-Z`, `0-9`, `-`, `.`
Property name `P`	min. `1`	`a-z`, `0-9`, `-`, `.`

Request Body (POST)

A POST request can be used to update one or more properties of an existing dataset, which is identified by the given token T. If the token T was not found, a new dataset related to this token is created. The POST payload needs to contain the a JSON object in Content-Type: application/json.

Example:

If the given dataset, which is related to token testdata:

{
  "firstname": "Max",
  "lastname": "Mustermann"
}

is updated via POST /api.php?token=testdata containing the Content-Type: application/json payload:

{
  "firstname": "Hans",
  "town": "New York"
}

it will return the updated dataset as JSON object as:

{
  "firstname": "Hans",
  "lastname": "Mustermann",
  "town": "New York"
}

Error Response Messages

In case of errors, a HTTP response code different from 200 (OK) is returned together with an JSON object describing the error.

{
  "kind": "error",
  "code": 400,
  "message": "Token contains invalid characters. Only letters, numbers, dots and dashes are allowed."
}

Possible errors:

Code	Message
`400` Bad Request	Content is not valid JSON.
`400` Bad Request	Invalid content type. Expected application/json.
`400` Bad Request	No token given.
`400` Bad Request	Not implemented.
`400` Bad Request	Token contains invalid characters. Only letters, numbers, dots and dashes are allowed.
`400` Bad Request	Token is too short. Must be at least 8 characters long.
`404` Not found	Dataset not found.
`404` Not found	Property not found in dataset.
`500` Internal Error	Not configured.

License

See LICENSE.

ramdacxp / dcache