Merge pull request #251 from matrix-org/daniel/guestshiz

Clarify guest /events and /sync

api/client-server/guest_events.yaml

@@ -28,6 +28,10 @@ paths:
 
         This API is the same as the non-guest /events endpoint, but can be
         called by guest users.
+
+        Note that the non-guest ``/events`` endpoint has been deprecated. This
+        API will also be deprecated at some point, but its replacement is not
+        yet known.
       security:
         - accessToken: []
       parameters:

specification/modules/guest_access.rst

@@ -65,6 +65,11 @@ They will only return events which happened while the room state had the
 value ``world_readable``. Guest clients do not need to join rooms in order to
 receive events for them.
 
+The intention is that guest users will call ``/events`` once per room in
+parallel for rooms they wish to view without joining. For rooms they wish to
+join, they will call ``/join`` and receive events by calling ``/sync`` as
+non-guest users do.
+
 Server behaviour
 ----------------
 Servers are required to only return events to guest accounts for rooms where