{"id":24020857,"url":"https://github.com/ramdacxp/dcache","last_synced_at":"2025-09-14T20:32:18.233Z","repository":{"id":248007683,"uuid":"827469275","full_name":"ramdacxp/dcache","owner":"ramdacxp","description":"JSON data cache for Home Assistant, TRMNL and more","archived":false,"fork":false,"pushed_at":"2024-07-18T21:23:05.000Z","size":113,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-19T05:30:35.019Z","etag":null,"topics":["home-assistant","php","rest-api","trmnl","webapi","webapp"],"latest_commit_sha":null,"homepage":"https://dcache.schademarmelade.de/","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramdacxp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-11T17:51:08.000Z","updated_at":"2024-07-18T21:23:08.000Z","dependencies_parsed_at":"2024-07-19T02:32:45.085Z","dependency_job_id":"021ced6e-31db-4b30-9126-386d781496ac","html_url":"https://github.com/ramdacxp/dcache","commit_stats":null,"previous_names":["ramdacxp/dcache"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramdacxp%2Fdcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramdacxp%2Fdcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramdacxp%2Fdcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramdacxp%2Fdcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramdacxp","download_url":"https://codeload.github.com/ramdacxp/dcache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233027375,"owners_count":18613647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-assistant","php","rest-api","trmnl","webapi","webapp"],"created_at":"2025-01-08T12:19:04.940Z","updated_at":"2025-01-08T12:19:22.044Z","avatar_url":"https://github.com/ramdacxp.png","language":"CSS","funding_links":[],"categories":["🏠 Plugins - Smart Home (Home Assistant, Energy)"],"sub_categories":[],"readme":"# dcache\n\n**dcache** is a PHP REST API implementing a JSON data cache.\n\n* The data cache consists of _data sets_ containing multiple _properties_ as key-value-pairs.\n* A _data set_ is identified by an unique _token_.\n* _Data Provider_ can create, update, and remove _data sets_.\n* _Consumer_ can query a _data set_ identified by the provided _token_.\n\nA running demo is available at: \u003chttps://dcache.schademarmelade.de/\u003e.\n\n![dcache Table View](doc/tableview.png)\n\nUsage examples:\n\n* Selected [Home Assistant](https:c//www.home-assistant.io/) entities can be pushed to **dcache** and visualized on a [TRMNL](https://usetrmnl.com/) e-ink display via a [custom TRMNL-Plugin](https://help.usetrmnl.com/en/articles/9510536-custom-plugins).\n* The result status of a DevOps build pipeline can be sent to **dcache** and visualized on a WLED led strip.\n* The battery status of multiple IoT devices is available in a single **dcache** data set.\n* ...\n\nA typical data flow between Home Assistant, **dcache**, and TRMNL could look like this:\n\n* HA provides `temperature=25`\n* HA provides `humidity=65`\n* TRMNL receives `{ temperature=25, humidity=65 }`\n* HA provides `fan=on`\n* HA provides `humidity=40`\n* TRMNL receives `{ temperature=25, humidity=40, fan=on }`\n\n## Server Setup\n\nSimply upload the `www` folder to your PHP enabled webserver and open the related address in a browser to setup your database connection.\n\n## Development Setup\n\nLocal development on Windows requires the following setup:\n\n* Install Git, NodeJs and VSCode.\n* Clone the GitHub repo `https://github.com/ramdacxp/dcache` in VSCode.\n* Open the created local folder in VSCode and confirm the installation of all recommended extensions.\n* Install PHP and MariaDB locally into a `bin` subfolder by executing `npm install`.\n* Import database test data via `reset-testdata.cmd`.\n\nThe installation can be repeated by executing the related `install-xxx.cmd` batch files.\nNo system wide settings are modified during the installation.\n\nThe database content can be reset to the initial test data with `reset-testdata.cmd`.\nAlready existing data in dcache tables will be removed!\n\nAll tools and test data can be removed completely by deleting the `bin` and `node_modules` sub-folders.\n\n## Run dcache locally\n\n* Execute `npm start` or choose `Terminal \u003e Run Build Task...` in VSCode.\n* Open the local dev webserver address \u003chttp://localhost:8080/\u003e in your browser.\n* Stop the servers by pressing `Ctrl-C` in the Terminal window.\n\n## Settings\n\nIf the settings file `src/settings.php` is missing, a settings form is shown on the website to interactively configure the database connection.\nSimply accept the default values if using the development servers.\nOnce configured, the form is no longer available. To revert the configuration, the settings file `src/settings.php` needs to be removed.\n\nThe default `src/settings.php` will have the following content:\n\n```php\n\u003c?php\n$settings = [];\n$settings[\"database\"] = \"mysql:host=localhost;dbname=dcache\";\n$settings[\"user\"] = \"root\";\n$settings[\"password\"] = \"\";\n$settings[\"prefix\"] = \"dc-\";\n```\n\n## API Details\n\nThe REST API is exposed at `/api.php`.\n\nFor a list of supported requests and related responses, please refer to the [`requests.http`](./requests.http) sample file.\nAll requests can be executed against the provided PHP development webserver in order to test and debug the API.\nThis requires VSCode with the [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension installed.\n\n| Method | URL                                         | Description                               | Success Response                      |\n|--------|---------------------------------------------|-------------------------------------------|---------------------------------------|\n| GET    | `/api.php?token=T`                          | Query complete dataset `T`                | Dataset `T` as object `{...}`         |\n| GET    | `/api.php?token=T\u0026property=P`               | Query property `P` from dataset `T`       | Value of `P` as string `\"val\"`        |\n| GET²   | `/api.php?token=T\u0026property=P\u0026value=V`       | Update property `P` to `V` in dataset `T` | Updated dataset `T` as object `{...}` |\n| POST   | `/api.php?token=T`                          | Update provided properties in dataset `T` | Updated dataset `T` as object `{...}` |\n| DELETE | `/api.php?token=T`                          | Remove complete dataset `T`               | Boolean `true`                        |\n| DELETE | `/api.php?token=T\u0026property=P`               | Remove property `P` from dataset `T`      | Boolean `true`                        |\n| GET³   | `/api.php?method=delete\u0026token=T`            | Remove complete dataset `T`               | Boolean `true`                        |\n| GET³   | `/api.php?method=delete\u0026token=T\u0026property=P` | Remove property `P` from dataset `T`      | Boolean `true`                        |\n\nAdditional `GET` methods as available to use the complete REST API from a regular web browser:  \n² - This `GET` method behaves like a `POST` of the single property `P`.  \n³ - With the parameter `method=delete` the `DELETE` requests can be invoked via `GET`.\n\n### Restrictions\n\n| Type              | Length   | Characters                    |\n|-------------------|----------|-------------------------------|\n| Dataset token `T` | min. `8` | `a-z`, `A-Z`, `0-9`, `-`, `.` |\n| Property name `P` | min. `1` | `a-z`, `0-9`, `-`, `.`        |\n\n### Request Body (POST)\n\nA `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`.\n\nExample:\n\nIf the given dataset, which is related to token `testdata`:\n\n```json\n{\n  \"firstname\": \"Max\",\n  \"lastname\": \"Mustermann\"\n}\n```\n\nis updated via `POST /api.php?token=testdata` containing the `Content-Type: application/json` payload:\n\n```json\n{\n  \"firstname\": \"Hans\",\n  \"town\": \"New York\"\n}\n```\n\nit will return the updated dataset as JSON object as:\n\n```json\n{\n  \"firstname\": \"Hans\",\n  \"lastname\": \"Mustermann\",\n  \"town\": \"New York\"\n}\n```\n\n### Error Response Messages\n\nIn case of errors, a HTTP response code different from `200` (OK) is returned together with an JSON object describing the error.\n\n```json\n{\n  \"kind\": \"error\",\n  \"code\": 400,\n  \"message\": \"Token contains invalid characters. Only letters, numbers, dots and dashes are allowed.\"\n}\n```\n\nPossible errors:\n\n| Code                 | Message                                                                                |\n|----------------------|----------------------------------------------------------------------------------------|\n| `400` Bad Request    | Content is not valid JSON.                                                             |\n| `400` Bad Request    | Invalid content type. Expected application/json.                                       |\n| `400` Bad Request    | No token given.                                                                        |\n| `400` Bad Request    | Not implemented.                                                                       |\n| `400` Bad Request    | Token contains invalid characters. Only letters, numbers, dots and dashes are allowed. |\n| `400` Bad Request    | Token is too short. Must be at least 8 characters long.                                |\n| `404` Not found      | Dataset not found.                                                                     |\n| `404` Not found      | Property not found in dataset.                                                         |\n| `500` Internal Error | Not configured.                                                                        |\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framdacxp%2Fdcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framdacxp%2Fdcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framdacxp%2Fdcache/lists"}