1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
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 user 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
{
"user": {
"name": "example username",
"id": "U1234abcd"
},
"resume_point": 1312,
"heartbeat": 30,
"users": [
{
"id": "U1234abcd",
"name": "example username"
}
],
"channels": [
{
"name": "nonsense and such",
"id": "C1234abcd"
}
],
"messages": [
{
"at": "2024-09-27T23:19:10.208147Z",
"channel": "C1234abcd",
"sender": "U1234abcd",
"id": "M1312acab",
"body": "beep"
}
]
}
```
The response will include the following fields:
| Field | Type | Description |
|:---------------|:----------------|:-------------------------------------------------------------------------------------------------------------------------|
| `user` | 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. |
| `heartbeat` | integer | The [heartbeat timeout](./events.md#heartbeat-events), in seconds, for events. |
| `users` | array of object | A snapshot of the users 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 `user` 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 `users` array describes a distinct user, and will include the following fields:
| Field | Type | Description |
|:-------|:-------|:-------------------------------------------------------------------------------------------------------------------------------------|
| `name` | string | The name for the user. |
| `id` | string | A unique identifier for the user. This can be used to associate the user with other events, or to make API calls targeting the user. |
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 user 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. |
|
