From d171a258ad2119e39cb715f8800031fff16967dc Mon Sep 17 00:00:00 2001
From: Owen Jacobson <owen@grimoire.ca>
Date: Tue, 1 Oct 2024 22:43:18 -0400
Subject: Provide a resume point to bridge clients from state snapshots to the
 event sequence.

---
 docs/api.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/api.md b/docs/api.md
index e18c6d5..5adf28d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -23,7 +23,8 @@ Returns information needed to boot the client. Also the recommended way to check
     "login": {
         "name": "example username",
         "id": "L1234abcd",
-    }
+    },
+    "resume_point": "1312",
 }
 ```
 
@@ -80,6 +81,10 @@ Channels are the containers for conversations. The API supports listing channels
 
 Lists channels.
 
+#### Query parameters
+
+This endpoint accepts an optional `resume_point` query parameter. If provided, the value must be the value obtained from the `/api/boot` method. This parameter will restrict the returned list to channels as they existed at a fixed point in time, with any later changes only appearing in the event stream.
+
 #### On success
 
 Responds with a list of channel objects, one per channel:
@@ -152,9 +157,13 @@ Subscribes to events. This endpoint returns an `application/event-stream` respon
 
 The returned stream may terminate, to limit the number of outstanding messages held by the server. Clients can and should repeat the request, using the `Last-Event-Id` header to resume from where they left off. Events will be replayed from that point, and the stream will resume.
 
+#### Query parameters
+
+This endpoint accepts an optional `resume_point` query parameter. If provided, the value must be the value obtained from the `/api/boot` method. This parameter start the returned stream immediately after the `resume_point`.
+
 #### Request headers
 
-This endpoint accepts an optional `Last-Event-Id` header for resuming an interrupted stream. If this header is provided, it must be set to the `id` field sent with the last event the client has processed. When `Last-Event-Id` is sent, the response will resume immediately after the corresponding event. If this header is omitted, then the stream will start from the beginning.
+This endpoint accepts an optional `Last-Event-Id` header for resuming an interrupted stream. If this header is provided, it must be set to the `id` field sent with the last event the client has processed. When `Last-Event-Id` is sent, the response will resume immediately after the corresponding event. This header takes precedence over the `resume_point` query parameter; if neither is provided, then event playback starts at the beginning of time (_you have been warned_).
 
 If you're using a browser's `EventSource` API, this is handled for you automatically.
 
-- 
cgit v1.2.3