api: Document the /register API with a lot more detail.

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
 <div class="code-section" markdown="1">

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

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
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -74,10 +108,6 @@ zulip(config).then((client) => {
 
 #### Example response
 
-**Note:** If you omit the `event_types` argument to `client.register()`,
-the JSON response will include the necessary initial data about
-all supported event types.
-
 A typical successful JSON response may look like:
 
 {generate_code_example|register-queue|fixture}

templates/zerver/help/include/rest_endpoints.md

@@ -22,7 +22,7 @@
 
 #### Real-time events
 * [Real time events API](/api/real-time-events)
-* [Register a queue](/api/register-queue)
-* [Get events from a queue](/api/get-events-from-queue)
-* [Delete a queue](/api/delete-queue)
+* [Register an event queue](/api/register-queue)
+* [Get events from an event queue](/api/get-events-from-queue)
+* [Delete an event queue](/api/delete-queue)