From bdf5a1504faffcd2d3977d371b1c471dd5a0e1a0 Mon Sep 17 00:00:00 2001
From: Joscha <joscha@plugh.de>
Date: Wed, 20 Dec 2023 13:23:13 +0100
Subject: [PATCH] Create first API draft

---
 API.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 API.md

diff --git a/API.md b/API.md
new file mode 100644
index 0000000..5538238
--- /dev/null
+++ b/API.md
@@ -0,0 +1,166 @@
+# The Forst API
+
+A client communicates with a Forst server using JSON packets over one or more
+WebSocket connections. A normal client does not need more than one connection,
+but can still use more if it is more convenient (e.g. multiple browser tabs).
+
+<!-- Implementing a client should be easy, especially implementing a bot. -->
+<!-- The API must be usable in the context of a web browser. -->
+<!-- The API should be robust if the connection is unstable (e.g. mobile data). -->
+
+## The connection lifecycle
+
+A connection has two phases: The **auth phase** and the **roam phase**. In each
+phase, only commands from the respective phase are allowed.
+
+A connection starts out in the **auth phase**. Here, the client and server must
+negotiate a client identity. When the client receives its identity, the
+connection switches to the roam phase.
+
+The connection now stays in the **roam phase** until it is closed. During this
+phase, the client can enter and exit rooms, as well as interact with other
+clients in entered rooms. The server will also send status updates (events) for
+entered rooms.
+
+## Primitive types
+
+### EventId
+
+A message id is a string matching `e[0-9a-f]{16}`. In other words, it's a 128
+bit hexadecimal integer prefixed by `e`.
+
+Sorting events by their id puts them in chronological order.
+
+### MessageId
+
+A message id is a string matching `m[0-9a-f]{16}`. In other words, it's a 128
+bit hexadecimal integer prefixed by `m`.
+
+Sorting messages by their id puts them in chronological order.
+
+### SessionId
+
+A session id is a string matching `s[0-9a-f]{16}`. In other words, it's a 128
+bit hexadecimal integer prefixed by `s`.
+
+### UserId
+
+A user id is a string matching `[a-z0-9-]+`. It is usually four characters long
+for accounts and eight characters plus a dash for other sessions, though this is
+not required. A user id uniquely identifies a user.
+
+<!-- Dashes are optional and carry no meaning. They can be added and removed at will. -->
+
+## Auth phase commands
+
+### `c-auth-cookie`
+
+Authenticate via the cookies exchanged during the HTTP handshake portion of the
+WebSocket connection. This requires the client to store and present the cookies
+on subsequent connections.
+
+### `c-auth-session-id`
+
+Authenticate via session id. This requires the client to store the session id
+and present it on subsequent connections via `auth-session-id`.
+
+### `c-auth-anon`
+
+Don't authenticate and obtain a unique user id for this session.
+
+## Roam phase events
+
+### `e-goodbye`
+
+When the server decides to close the connection, it may send a goodbye event
+explaining the decision beforehand, though this is not required.
+
+Possible reasons:
+
+- protocol error (e.g. using roam commands during the auth phase)
+- spam (the client is sending too many commands)
+- login (the client has logged into an account on another connection for the same session)
+- logout (the client has logged out of an account on another connection for the same session)
+
+## Roam phase commands
+
+### `c-enter`
+
+Enter a room. This is required for a client to receive room events and send room
+commands. A user that has entered a room in at least one client will be displayed
+in the nick list.
+
+As part of the reply to this command, the server will include the client's
+current room nick.
+
+### `c-exit`
+
+Exit a room. After exiting a room, the server will no longer relay events for
+that room, and the client can no longer issue commands for that room.
+
+### `c-login`
+
+## Roam phase room events
+
+### `e-enter`
+
+A user has entered the room.
+
+### `e-exit`
+
+A user has exited the room.
+
+### `e-nick`
+
+A user has changed their nick.
+
+### `e-send`
+
+A new message has been sent.
+
+### `e-edit`
+
+An existing message has been edited.
+
+### `e-delete`
+
+An existing message has been deleted.
+
+## Roam phase room commands
+
+### `c-nick`
+
+Change your own nick.
+
+### `c-send`
+
+Send a new message.
+
+### `c-edit`
+
+Edit a message.
+
+### `c-delete`
+
+Delete a message.
+
+### `c-get-msg`
+
+Request a specific message.
+
+This may be useful for clients like bots that don't want to store the entire
+message history.
+
+### `c-get-thread`
+
+Request one or more threads, optionally starting before a specific message id.
+
+If no message id is specified, the latest threads are returned. If a message id
+is specified, the first few threads older than that id are returned.
+
+### `c-get-log`
+
+Request event log, optionally starting before a specific event id.
+
+If no event id is specified, the latest events are returned. If an event id is
+specified, the first few events older than that id are returned.