Docs updates

1 files changed, 19 insertions, 9 deletions

diff --git a/docs/api.md b/docs/api.md
index ccbd60e..969e939 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -8,15 +8,9 @@ On errors, the response body is freeform text and is meant to be shown to the us
 
 Requests that require a JSON body must include a `content-type: application/json` header. For requests that take a JSON body, if the body does not match the required schema, the endpoint will return a 422 Unprocessable Entity response, instead of the responses documented for that endpoint.
 
-## Authentication
-
-Other than where noted below, all endpoints require authentication.
-
-To authenticate a request, send a `cookie: identity=YOUR TOKEN HERE` header in the request. Tokens can be obtained via the `/api/auth/login` endpoint. This authentication protocol is intended to integrate with browsers and browser-like environments, where the browser handles cookie headers automatically.
+## Client initialization
 
-If the token is not valid or has expired, then `hi` will send back a 401 Unauthorized response, instead of the responses documented for the endpoint the request was intended for.
-
-## Endpoints
+Clients will generally need some information about the session in order to present a coherent view to the user, including the session's login identity.
 
 ### `GET /api/boot`
 
@@ -33,6 +27,14 @@ Returns information needed to boot the client. Also the recommended way to check
 }
 ```
 
+## Authentication
+
+Other than where noted below, all endpoints require authentication.
+
+To authenticate a request, send a `cookie: identity=YOUR TOKEN HERE` header in the request. Tokens can be obtained via the `/api/auth/login` endpoint. This authentication protocol is intended to integrate with browsers and browser-like environments, where the browser handles cookie headers automatically.
+
+If the token is not valid or has expired, then `hi` will send back a 401 Unauthorized response, instead of the responses documented for the endpoint the request was intended for.
+
 ### `POST /api/auth/login`
 
 Authenticates the user by login name and password, creating a login if none exists. **This endpoint does not require an `identity` cookie.**
@@ -68,7 +70,11 @@ Invalidates the identity token, logging the user out.
 
 #### On success
 
-This endpoint returns a 204 No Content response on success, with a `Set-Cookie` header that clears the `identity` cookie. Even if this header is not processed, the cookie provided in the request is invalidated and will not authenticate future requests.
+This endpoint returns a 204 No Content response on success, with a `Set-Cookie` header that clears the `identity` cookie. The cookie provided in the request is also invalidated, and will not authenticate future requests even if the client fails to process the `Set-Cookie` response header.
+
+## Working with channels
+
+Channels are the containers for conversations. The API supports listing channels, creating new channels, and send messages to an existing channel.
 
 ### `GET /api/channels`
 
@@ -112,6 +118,10 @@ Creates a channel.
 
 Channel names must be unique. If a channel with the same name already exists, this will return a 400 Bad Request error.
 
+## Events
+
+The API delivers events to clients to update them on other clients' actions and messages. While there is no specific delivery deadline, messages are delivered as soon as possible on a best-effort basis, and the event system allows clients to replay events or resume interrupted streams, to allow recovery if a message is lost.
+
 ### `POST /api/channels/:channel`
 
 Sends a chat message to a channel. It will be relayed to clients subscribed to the channel's events, and recorded for replay.