API docs rewrite.

Having the whole API in a single file was starting to feel very cramped and constraining. This rewrite breaks it out into sections; as a side effect, the docs are now about 2.5x as long as they were, as the rewrite allows more space for each idea without crowding the page.

The docs are best read by running `tools/docs-api`.

1 files changed, 110 insertions, 0 deletions

diff --git a/docs/api/boot.md b/docs/api/boot.md
new file mode 100644
index 0000000..88f2d5b
--- /dev/null
+++ b/docs/api/boot.md
@@ -0,0 +1,110 @@
+# Client initialization
+
+```mermaid
+---
+Client lifecycle
+---
+sequenceDiagram
+	actor Andrea
+	participant API
+
+	Andrea ->>+ API : GET /api/boot
+	API -->- Andrea : Snapshot, resume_point=23
+
+	Andrea ->>+ API : GET /api/events?resume_point=23
+	loop
+	API -) Andrea : Event
+	end
+	API <<->>- Andrea: Disconnect
+```
+
+
+Client initialization serves three purposes:
+
+* It confirms that the client's [identity token](./authentication.md) is valid, and tells the client what login that token is associated with.
+* It provides an initial snapshot of the state of the service.
+* It provides a resume point for the [event stream](./events.md), which allows clients to consume events starting from the moment the snapshot was created.
+
+
+## `GET /api/boot`
+
+Returns the information needed to initialize a client.
+
+This method is also the recommended way to validate the client's identity token, and to check that the service is fully configured.
+
+### Success
+
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object containing the initial state for the client:
+
+```json
+{
+	"login": {
+		"name": "example username",
+		"id": "L1234abcd",
+	},
+	"resume_point": 1312,
+	"logins": [
+		{
+			"id": "L1234abcd",
+			"name": "example username"
+		}
+	],
+	"channels": [
+		{
+			"name": "nonsense and such",
+			"id": "C1234abcd",
+		}
+	],
+	"messages": [
+		{
+			"at": "2024-09-27T23:19:10.208147Z",
+			"channel": "C1234abcd",
+			"sender": "L1234abcd",
+			"id": "M1312acab",
+			"body": "beep"
+		}
+	]
+}
+```
+
+The response will include the following fields:
+
+| Field          | Type            | Description |
+|:---------------|:----------------|:--|
+| `login`        | object          | The details of the caller's identity. |
+| `resume_point` | integer         | A resume point for [events](./events.md), such that the event stream will begin immediately after the included snapshot. |
+| `logins`       | array of object | A snapshot of the logins present in the service. |
+| `channels`     | array of object | A snapshot of the channels present in the service. |
+| `messages`     | array of object | A snapshot of the messages present in the service. |
+
+The `login` object will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The name of the caller's login identity. |
+| `id`   | string | The ID of the caller's login identity. |
+
+
+Each element of the `logins` array describes a distinct login, and will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The name for the login. |
+| `id`   | string | A unique identifier for the login. This can be used to associate the login with other events, or to make API calls targeting the login. |
+
+Each element of the `channels` array describes a distinct channel, and will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The name for the channel. |
+| `id`   | string | A unique identifier for the channel. This can be used to associate the channel with other events, or to make API calls targeting the channel. |
+
+Each element of the `messages` array describes a distinct message, and will include the following fields:
+
+| Field     | Type      | Description |
+|:----------|:----------|:--|
+| `at`      | timestamp | The moment the message was sent. |
+| `channel` | string    | The ID of the channel the message was sent to. |
+| `sender`  | string    | The ID of the login that sent the message. |
+| `id`      | string    | A unique identifier for the message. This can be used to associate the message with other events, or to make API calls targeting the message. |
+| `body`    | string    | The text of the message. |