# 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.                                                                                                                      |