update documentation

DOCS.md

@@ -0,0 +1,29 @@
+Docs for almost every API path \
+
+Authentication is done with the `X-Token` header (doesn't apply to websocket see `PROTOCOL.md` for that) \
+All responses are in JSON, request body if required must also be JSON \
+TODO document errors
+
+## Paths
+
+### `/api/tokens/create`
+Required role: `admin`
+
+Method: `PUT` 
+
+Request body:
+- `accessLimits`: the label of access limits
+
+Response body:
+- `token`: the generated token (base64 encoded)
+
+
+### `/api/tokens/me`
+Required role: `user`
+
+Method: `GET`
+
+Response body:
+- `token`: the token itself but only first and last 5 characters visible separated by ...
+- `role`: the role like user or admin
+- `accessLimits`: the label of access limits

PROTOCOL.md

@@ -1,22 +1,27 @@
 This file documents the websocket /api/ws
 
-## Format
+## Message format
-Packet id then arguments \
+Always bytes! \
+Packet id followed by arguments \
 Some packets don't have arguments so send just the packet id \
-There can be multiple packets in one message, those with variable length arguments have to be terminated \
+There can be multiple packets in one message, those with unknown amount of arguments have to be terminated \
-Numbers are signed
+All number types are signed
 
 ## Authentication
+Unsurprisingly, tokens are used to authenticate.
+
 The first message from the server is:
 - `0x6d 0x73`
 
-The client should reply, in a single message:
+The client replies with a single message:
 1. `0xb6 0xc4`
-2. client version (byte), right now it's 0
+2. client version (byte), currently it's `0` and won't change until everything is complete
 3. length of access key (byte)
-4. access key, decoded from base64
+4. token (bytes), decoded from base64
 
-Authentication complete, the server will send a disconnect if something's wrong, otherwise it will pong. \
+Authentication complete. \
+If something's wrong the server disconnects, see below for reason codes. \
+Otherwise the client receives a pong. \
 No commands are handled during this time
 
 # Commands
@@ -33,7 +38,7 @@ No commands are handled during this time
 | `0x00` | Pong | 1. long: unix millis | A response to ping, also sent by server on successful authentication |
 
 ## Disconnect reasons
-On every disconnect there's a human-readable message the client should display
+Alongside code, there's always a human-readable message which contains more specific information
 
 | Code   | Name               | Notes                                           |
 |--------|--------------------|-------------------------------------------------|

pom.xml

@@ -50,6 +50,10 @@
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-websockets</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-rest-jackson</artifactId>
+        </dependency>
     </dependencies>
 
     <build>