diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api.md | 12 |
1 files changed, 5 insertions, 7 deletions
diff --git a/docs/api.md b/docs/api.md index 969e939..8bb3c0b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -156,20 +156,22 @@ The returned stream may terminate, to limit the number of outstanding messages h This endpoint accepts the following query parameters: -* `channel`: a channel ID. Events for this channel will be included in the response. This parameter may be provided multiple times. +* `channel`: a channel ID to subscribe to. Events for this channel will be included in the response. This parameter may be provided multiple times. Clients should not subscribe to the same channel more than once in a single request. Browsers generally limit the number of open connections, often to embarrassingly low limits. Clients should subscribe to multiple streams in a single request, and should not subscribe to each stream individually. -Requests without parameters will be successful, but will return an empty stream. +Requests without a subscription return an empty stream. (If you're wondering: it has to be query parameters or something equivalent to it, since `EventSource` can only issue `GET` requests.) #### 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` of the last event processed by the client. The new stream will resume immediately after that 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. If this header is omitted, then the stream will start from the beginning. If you're using a browser's `EventSource` API, this is handled for you automatically. +The event IDs `hi` sends in `application/event-stream` encoding are ephemeral, and can only be reused within the brief intervals required to reconnect to the event stream. Do not store them, and do not parse them. The message data's `"id"` field is the durable identifier for each message. + #### On success The returned event stream is a sequence of events: @@ -187,7 +189,3 @@ data: "body": "my amazing thoughts, by bob", data: "sent_at": "2024-09-19T02:30:50.915462Z" data: } ``` - -The event `id` (`1234`, in the example above) is used to support resuming the stream after an interruption. See the "Request headers" section, above, for details. Event IDs are ephemeral, and can only be reused within the brief intervals required to reconnect to the event stream. Do not store them, and do not parse them. - -The `"id"` field uniquely identifies the message in related API requests, but is not used to resume the stream. |