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