diff --git a/templates/zerver/api/get-events-from-queue.md b/templates/zerver/api/get-events-from-queue.md index b7e4bee4a7..7d1af12137 100644 --- a/templates/zerver/api/get-events-from-queue.md +++ b/templates/zerver/api/get-events-from-queue.md @@ -1,10 +1,9 @@ -# Get events from a queue +# Get events from an event queue `GET {{ api_url }}/v1/events` -This endpoint allows you to receive new events from an event queue that -can be created by -[requesting the `{{ api_url}}/v1/register` endpoint](/api/register-queue). +This endpoint allows you to receive new events from +[a registered event queue](/api/register-queue). ## Usage examples
diff --git a/templates/zerver/api/real-time-events.md b/templates/zerver/api/real-time-events.md index acdaf3b665..8a6abcc60b 100644 --- a/templates/zerver/api/real-time-events.md +++ b/templates/zerver/api/real-time-events.md @@ -61,11 +61,3 @@ client.call_on_each_event(lambda event: sys.stdout.write(str(event) + "\n")) You may also pass in the following keyword arguments to `call_on_each_event`: {generate_api_arguments_table|arguments.json|call_on_each_event} - -## Deeper implementation details - -If you're developing a Zulip client or otherwise want deeper details, -you can consult the -[developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/events-system.html) -for how Zulip's event system works. - diff --git a/templates/zerver/api/register-queue.md b/templates/zerver/api/register-queue.md index 199fc0d852..57c132f9e9 100644 --- a/templates/zerver/api/register-queue.md +++ b/templates/zerver/api/register-queue.md @@ -1,15 +1,49 @@ -# Register a queue - -Register a queue to receive new messages. - -(This endpoint is used internally by the API, and it is -documented here for advanced users that want to customize -how they register for Zulip events. The `queue_id` returned -from this endpoint can be used in a subsequent call to the -["events" endpoint](/api/get-events-from-queue).) +# Register an event queue `POST {{ api_url }}/v1/register` +This powerful endpoint can be used to register a Zulip "event queue" +(subscribed to certain types of "events", or updates to the messages +and other Zulip data the current user has access to), as well as to +fetch the current state of that data. + +(`register` also powers the `call_on_each_event` Python API, and is +intended primarily for complex applications for which the more convenient +`call_on_each_event` API is insufficient). + +This endpoint returns a `queue_id` and a `last_event_id`; these can be +used in subsequent calls to the +["events" endpoint](/api/get-events-from-queue) to request events from +the Zulip server using long-polling. + +The server will queue events for up to 10 minutes of inactivity. +After 10 minutes, your event queue will be garbage-collected. The +server will send `heartbeat` events every minute, which makes it easy +to implement a robust client that does not miss events unless the +client loses network connectivity with the Zulip server for 10 minutes +or longer. + +Once the server garbage-collects your event queue, the server will +return an error with a code of `BAD_EVENT_QUEUE_ID` if you try to +connect to the event queue. Your software will need to handle that +error condition by re-initializing itself (e.g. this is what triggers +your browser reloading the Zulip webapp when your laptop comes back +online after being offline for more than 10 minutes). + +When prototyping with this API, we recommend first calling `register` +with no `event_types` argument to see all the available data from all +supported event types. Before using your client in production, you +should set appropriate `event_types` and `fetch_event_types` filters +so that your client only requests the data it needs. A few minutes +doing this often saves 90% of the total bandwidth and other resources +consumed by a client using this API. + +See the +[events system developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/events-system.html) +if you need deeper details about how the Zulip event queue system +works, avoids clients needing to worry about large classes of +potentially messy races, etc. + ## Usage examples