From 95c92920695ed06b214f11d8d2a1b7c43c11b3a4 Mon Sep 17 00:00:00 2001
From: luto <m@luto.at>
Date: Sat, 24 Feb 2024 23:10:21 +0100
Subject: [PATCH] add docs for things

---
 docs/THINGS.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 docs/THINGS.md

diff --git a/docs/THINGS.md b/docs/THINGS.md
new file mode 100644
index 0000000..1ced9b9
--- /dev/null
+++ b/docs/THINGS.md
@@ -0,0 +1,43 @@
+# Things
+
+MOS allows admins to maintain a list of Things (=devices, machines, permissions, ...)
+and attach uses to them, e.g. user "ripper" is allowed to use thing "laser".
+Additionally, things may report being used, e.g. "ripper" used "laser" for 60
+seconds.
+
+## Auth
+
+Most endpoints require authentication. Ask Vorstand for a token and provide it
+in the `X-TOKEN` header.
+
+## Getting key IDs allowed to operate a Thing
+
+```
+$ curl https://metalab.at/things/keys/prusaxl -H "X-TOKEN: XXX"
+00-000000000001,luto
+00-000000000002,ripper
+```
+
+## Reporting usage of a thing
+
+```
+$ curl https://metalab.at/things/usage/prusaxl -H "X-TOKEN: XXX" -XPOST -d 'user=luto&kind=LOGIN'
+```
+
+`kind` may be:
+
+* `LOGIN`, user started using a machine
+* `LOGOUT`, user stopped using a machine
+* `USAGE_MEMBER`, user used the machine for X seconds, for a member
+* `USAGE_NONMEMBER`, user used the machine for X seconds, for a non-member
+
+Additionally, supply `usage_seconds=` for `USAGE_` kinds.
+
+## Getting stats for a Thing
+
+```
+$ curl https://metalab.at/things/stats/laser
+[["2024-02-24", 1], ["2024-02-24", 1]]
+```
+
+Format: `[[date of usage, usage in seconds],...]`.