diff options
Diffstat (limited to 'docs/api/events.md')
| -rw-r--r-- | docs/api/events.md | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/docs/api/events.md b/docs/api/events.md new file mode 100644 index 0000000..9fe9ca9 --- /dev/null +++ b/docs/api/events.md @@ -0,0 +1,213 @@ +# Events + +```mermaid +--- +Events flow through it +--- +sequenceDiagram + actor Andrea + participant API + actor Blake + + Note over Andrea,Blake: Subscribing to events + + Andrea ->> API : Subscribe + Blake ->> API : Subscribe + + Note over Andrea,Blake: Sending a message + + Andrea ->>+ API : Send "hello, world!" + API -->>- Andrea : Accepted + + Note over Andrea,Blake: Receiving events + + par + API --) Andrea : Andrea sent "hello, world!" + and + API --) Blake : Andrea sent "hello, world!" + end +``` + +The core of the service is to facilitate conversations between logins. Conversational activity is delivered to clients using _events_. Each event notifies interested clients of activity sent to the service through its API. + + +## `GET /api/events` + +Subscribes to events. + +This endpoint is designed for use with the [EventSource] DOM API, and supports several features of that API, as described below. Other clients may implement these features for themselves. + +[EventSource]: https://developer.mozilla.org/en-US/docs/Web/API/EventSource + +### Query parameters + +This endpoint accepts an optional `resume_point` (integer) query parameter. When provided, the event stream will include events published after that point in time; the value must be the value obtained by calling the [`GET /api/boot`](./boot.md) method. If absent, the returned event stream includes all events. + +### Request headers + +This endpoint accepts an optional `last-event-id` (string) header. If present, the value must be the value of the `id` field of the last message processed by the client. The returned event stream will begin with the following message. If absent, the returned event stream will begin from the start of the event collection. + +This header is set automatically by `EventSource` when reconnecting to an event stream. + +### Success + +This endpoint will respond with a status of `200 Okay` when successful. The body of the response is an [event stream]: + +[event stream]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format + +``` +id: 1234 +data: { +data: "type": "message", +data: "event": "sent", +data: "at": "2024-09-27T23:19:10.208147Z", +data: "channel": "C9876cyyz", +data: "sender": "L1234abcd", +data: "id": "M1312acab", +data: "body": "beep" +data: } +``` + +The service will keep the connection open, and will deliver events as they occur. + +The service may terminate the connection at any time. Clients should reconnect and resume the stream, using the `last-event-id` header to resume from the last message received. The `id` of each event is an ephemeral ID, useful only for this purpose. + +Each event's `data` consists of a JSON object describing one event. Every event includes the following fields: + +| Field | Type | Description | +|:--------|:-------|:--| +| `type` | string | The type of entity the event describes. Will be one of the types listed in the next section. | +| `event` | string | The specific kind of event. Will be one of the events listed with the associated `type` in the next section. | + +The remaining fields depend on the `type` and `event` field. + + +## Login events + +The following events describe changes to logins. + +These events have the `type` field set to `"login"`. + +### Login created + +```json +{ + "type": "login", + "event": "created", + "at": "2024-09-27T23:17:10.208147Z", + "id": "L1234abcd", + "name": "example username" +} +``` + +Sent whenever a new login is created. + +These events have the `event` field set to `"created"`. They include the following additional fields: + +| Field | Type | Description | +|:-------|:----------|:--| +| `at` | timestamp | The moment the login was created. | +| `id` | string | A unique identifier for the newly-created login. This can be used to associate the login with other events, or to make API calls targeting the login. | +| `name` | string | The login's name. | + + +## Channel events + +The following events describe changes to [channels](./channels-messages.md). + +These events have the `type` field set to `"channel"`. + +### Channel created + +```json +{ + "type": "channel", + "event": "created", + "at": "2024-09-27T23:18:10.208147Z", + "id": "C9876cyyz", + "name": "example channel 2" +} +``` + +Sent whenever a new channel is created. + +These events have the `event` field set to `"created"`. They include the following additional fields: + +| Field | Type | Description | +|:-------|:----------|:--| +| `at` | timestamp | The moment the channel was created. | +| `id` | string | A unique identifier for the newly-created channel. This can be used to associate the channel with other events, or to make API calls targeting the channel. | +| `name` | string | The channel's name. | + +### Channel deleted + +```json +{ + "type": "channel", + "event": "deleted", + "at": "2024-09-28T03:40:25.384318Z", + "id": "C9876cyyz" +} +``` + +Sent whenever a channel is deleted or expires. + +These events have the `event` field set to `"deleted"`. They include the following additional fields: + +| Field | Type | Description | +|:------|:----------|:--| +| `at` | timestamp | The moment the channel was deleted. | +| `id` | string | The deleted channel's ID. | + + +## Message events + +The following events describe changes to [messages](./channels-messages.md). + +These events have the `type` field set to `"message"`. + +### Message sent + +```json +{ + "type": "message", + "event": "sent", + "at": "2024-09-27T23:19:10.208147Z", + "channel": "C9876cyyz", + "sender": "L1234abcd", + "id": "M1312acab", + "body": "an effusive blob of prose, condensed down to a single string" +} +``` + +Sent whenever a message is sent by a client. + +These events have the `event` field set to `"sent"`. They include the following additional 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. | + +### Message deleted + +```json +{ + "type": "message", + "event": "deleted", + "at": "2024-09-28T02:44:27.077355Z", + "id": "M1312acab" +} +``` + +Sent whenever a message is deleted or expires. + +These events have the `event` field set to `"deleted"`. They include the following additional fields: + +| Field | Type | Description | +|:------|:----------|:--| +| `at` | timestamp | The moment the message was deleted. | +| `id` | string | The deleted message's ID. | |