From 77bc81a2f623837a08b4c2512314917f662c546e Mon Sep 17 00:00:00 2001
From: Christopher Vagnetoft <cvagnetoft@gmail.com>
Date: Thu, 13 Mar 2025 23:30:05 +0100
Subject: [PATCH] Update docs

---
 README.md | 129 +++++++++++++++++++++++++++++++++++-------------------
 TODO.md   |   6 +++
 2 files changed, 91 insertions(+), 44 deletions(-)
 create mode 100644 TODO.md

diff --git a/README.md b/README.md
index cb68fd2..fe06a22 100644
--- a/README.md
+++ b/README.md
@@ -3,74 +3,115 @@
 SlotDB is an application designed to store information about property or assets, to
 be able to query on that information, and implement basic schemas.
 
+Use cases:
+
+- **Warehousing** — Keep track of warehouse locations, available stock and more.
+- **Hospitality** — Manage inventory of rooms or camping spots, together with availability,
+  price rates, available amenities, current guest etc.
+- **Restaurants** — Keep track of tables and orders.
+- **Shows and Events** — Allocate seating, with information on the guest and what level
+  ticket was purchased.
+
 ## Installing
 
 ### Docker
 
 ```bash
 $ docker run -it \
+    -p 8080:8080
     -v $PWD/slotdb.json:/app/slotdb.json \
     dev.noccylabs.info/slotdb/slotdb
 ```
 
 ## Configuration
 
-## API
+## Security
 
-### /api/slotdb/v1/slots [GET]
+> [!NOTE]
+> Security is not yet implemented. This section is a draft of how things may work.
 
-**Get a list of all slots, or slots matching conditions**
+Security is configured using an ACL embedded in the JWT. Each entry in the ACL follows
+the following format:
 
-```json
-GET /api/slotdb/v1/slots
-
-HTTP 200 OK
-Content-Type: application/json
-
-{
-  "slots": [
-    {
-      "id": "1.1",
-      "name": "First thing",
-      "available": true
-    }
-  ]
-}
+```text
+[groupid#][slot][.prop][/access]
+ ¯¯¯¯¯¯¯¯\¯¯¯¯¯¯\¯¯¯¯¯\ ¯¯¯¯¯¯¯\
+          \      \     \        Can be either '/rw' (default), '/r' or '/w'
+           \      \     Property name or wildcard pattern (default: .*)
+            \      Slot ID or wildcard pattern (default: *)
+             Group ID
 ```
 
-```json
-GET /api/slotdb/v1/slots?get=id&where[]=available:1
+Examples:
 
-HTTP 200 OK
-Content-Type: application/json
+| ACE             | Meaning
+| --------------- | ------------------------------------------
+| `/rw`           | Read and write everything
+| `A#`            | Read and write everything in group 'A'
+| `room*:x-*`     | Read and write all properties starting with 'x-' on slots starting with 'room'
+| `*/r`           | Read-only access to everything
+| `.available/rw` | Read and write the 'available' property on all slots, and nothing else
 
-{
-  "slots": [
-    {
-      "id": "1.1"
-    },
-    {
-      "id": "1.2"
-    }
-  ]
-}
+## Using the API
+
+For the full API, see [doc/slotdb.openapi.yaml](doc/slotdb.openapi.yaml).
+
+### Creating some slots
+
+To create slot:
+
+```bash
+$ curl -XPOST -Hcontent-type:application/json --data \
+    '[{"slot":"A1","name":"Room A1"},{"slot":"A2","name":"Room A2"}]' \
+    http://127.0.0.1:8080/api/slotdb/v1/slots
 ```
 
-| Params               | Value
-| -------------------- | --------
-| page                 | Page
-| limit                | The number of results (per page) to return
-| get                  | Comma-separated list of keys to return
-| {key}:[cond]{match}  | Match condition
+The created slots will be returned.
 
-Combine like: `?where[]=available:1&where[]=rate-group:<=2`
+### Creating groups
 
-### /api/slotdb/v1/slots [POST]
+To create group:
 
-**Create one or more new slots**
+```bash
+$ curl -XPOST -Hcontent-type:application/json --data \
+    '[{"group":"A","name":"Building A"}]' \
+    http://127.0.0.1:8080/api/slotdb/v1/groups
+```
 
-### /api/slotdb/v1/slot/{slot} [GET]
+Add members using the special `_members` property, and set some properties
+while we're at it:
 
-### /api/slotdb/v1/slot/{slot} [PUT]
+```bash
+$ curl -XPOST -Hcontent-type:application/json --data \
+    '{"_members":{"A1":true,"A2":true},"rate":399,"available":true}' \
+    http://127.0.0.1:8080/api/slotdb/v1/group/A
+```
+
+### Updating slots
+
+Set properties:
+
+```bash
+$ curl -XPOST -Hcontent-type:application/json --data \
+    '{"available":false}' \
+    http://127.0.0.1:8080/api/slotdb/v1/slot/A1
+```
+
+Get all slots:
+
+```bash
+$ curl http://127.0.0.1:8080/api/slotdb/v1/slots
+```
+
+Only get the available slots:
+
+```bash
+$ curl http://127.0.0.1:8080/api/slotdb/v1/slots?where[]=available:1
+```
+
+Get the slots in a group:
+
+```bash
+$ curl http://127.0.0.1:8080/api/slotdb/v1/group/A/members
+```
 
-### /api/slotdb/v1/slot/{slot} [DELETE]
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..22a91ca
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,6 @@
+# SlotDB TODO
+
+- [ ] Security
+  - [ ] JWT authentication
+    - [ ] Access control on groups, slots and props
+  - [ ] Token authentication