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, 141 insertions, 0 deletions

diff --git a/docs/api/channels-messages.md b/docs/api/channels-messages.md
new file mode 100644
index 0000000..d032ac1
--- /dev/null
+++ b/docs/api/channels-messages.md
@@ -0,0 +1,141 @@
+# Channels and messages
+
+```mermaid
+---
+Channel lifecycle
+---
+stateDiagram-v2
+	[*] --> Active : POST /api/channels
+	Active --> Deleted : DELETE /api/channels/C1234
+	Active --> Deleted : Expiry
+	Deleted --> [*]
+```
+
+```mermaid
+---
+Message lifecycle
+---
+stateDiagram-v2
+	[*] --> Sent : POST /api/channels/C1234
+	Sent --> Deleted : DELETE /api/messages/Mabcd
+	Sent --> Deleted : Expiry
+	Deleted --> [*]
+```
+
+Messages allow logins to communicate with one another. Channels are the conversations to which those messages are sent.
+
+Every channel has a unique name, chosen when the channel is created.
+
+Both channels and messages expire after a time, to prevent the service from consuming unlimited amounts of storage. Messages expire 90 days after being sent. Channels expire 90 days after the last message sent to them, or after creation if no messages are sent in that time.
+
+
+## `POST /api/channels`
+
+Creates a channel.
+
+### Request
+
+```json
+{
+	"name": "a unique channel name"
+}
+```
+
+The request must have the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The channel's name. |
+
+### Success
+
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the new channel:
+
+```json
+{
+	"name": "a unique channel name",
+	"id": "C9876cyyz"
+}
+```
+
+The response will have the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The channel's name. |
+| `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. |
+
+### Duplicate channel name
+
+This endpoint will respond with a status of `409 Conflict` if a channel with the requested name already exists.
+
+
+## `POST /api/channels/:id`
+
+Sends a message to a channel.
+
+This endpoint requires the following path parameter:
+
+| Parameter | Type   | Description |
+|:----------|:-------|:--|
+| `id`      | string | A channel ID. |
+
+### Request
+
+```json
+{
+	"body": "my amazing thoughts, by bob"
+}
+```
+
+The request must have the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `body` | string | The message to deliver to the channel. |
+
+### Success
+
+This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.
+
+### Invalid channel ID
+
+This endpoint will respond with a status of `404 Not Found` if the channel ID is not valid.
+
+
+## `DELETE /api/channels/:id`
+
+Deletes a channel (and all messages in it).
+
+This endpoint requires the following path parameter:
+
+| Parameter | Type   | Description |
+|:----------|:-------|:--|
+| `id`      | string | A channel ID. |
+
+### Success
+
+This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.
+
+### Invalid channel ID
+
+This endpoint will respond with a status of `404 Not Found` if the channel ID is not valid.
+
+
+## `DELETE /api/messages/:id`
+
+Deletes a message.
+
+This endpoint requires the following path parameter:
+
+| Parameter | Type   | Description |
+|:----------|:-------|:--|
+| `id`      | string | A message ID. |
+
+### Success
+
+This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.
+
+### Invalid message ID
+
+This endpoint will respond with a status of `404 Not Found` if the message ID is not valid.