Refactor document to be clearer on where the APIs are. Mark each one as either TODO, ONGOING, Draft or Final.

drafts/general_api.rst

@@ -1,31 +1,40 @@
 Instant Messaging
 =================
+
+Legend:
+ - ``TODO``: API is not in this document yet.
+ - ``ONGOING``: API is proposed but needs more work. There are known issues to be
+   addressed.
+ - ``Draft``: API is proposed and has no outstanding issues to be addressed, but
+   needs more feedback.
+ - ``Final``:  The API has no outstanding issues.
+
 This contains the formal proposal for Matrix Client-Server API v2. This API 
 would completely replace v1. It is a general API, not specific to any particular 
 protocol e.g. HTTP. It contains the following APIs:
 
-- Filtering API
+- Filtering API ``ONGOING``
-- Global initial sync API
+- Global initial sync API ``ONGOING``
-- Event stream API
+- Event stream API ``Draft``
-- Room creation API
+- Room creation API ``Draft``
-- Room joining API
+- Room joining API ``Draft``
-- Scrollback API
+- Scrollback API ``Draft``
-- Contextual windowing API
+- Contextual windowing API ``Draft``
 - Action APIs:
-   - Inviting
+   - Inviting ``Final``
-   - Rejecting invites
+   - Rejecting invites ``Final``
-   - Leaving
+   - Leaving ``Final``
-   - Kicking
+   - Kicking ``Final``
-   - Banning
+   - Banning ``Final``
-   - Sending message events
+   - Sending message events ``ONGOING``
-   - Sending state events
+   - Sending state events ``Final``
-   - Deleting state events
+   - Deleting state events ``Draft``
-- Presence API
+- Presence API ``ONGOING``
-- Typing API
+- Typing API ``ONGOING``
-- Capabilities API
+- Capabilities API ``ONGOING``
-- ``TODO`` Room Directory API
+- Room Directory API ``TODO``
-- ``TODO`` Public room list API
+- Public room list API ``TODO``
-- ``TODO`` User Profile API
+- User Profile API ``TODO``
 
 The following APIs will remain unchanged from v1:
 
@@ -35,40 +44,20 @@ The following APIs will remain unchanged from v1:
 
 It also contains information on changes to events, including:
 
-- Relates to
+- Action IDs ``ONGOING``
-- Updates
+- Sessions ``ONGOING``
-- State key restrictions
+- Relates to ``Draft``
-- Event type rule setting
+- Updates ``Draft``
+- State key restrictions ``Draft``
+- Event type rule setting ``Draft``
 
 Notes
 -----
 
 TODO
 ~~~~
-- Pagination: Would be nice to have "and X more". It will probably be 
-  Google-style estimates given we can't know the exact number over federation, 
-  but as a purely informational display thing it would be nice.
-- HTTP Ordering: Blocking requests with higher seqnums is troublesome if there 
-  is a max # of concurrent connections a client can have open. 
-- Session expiry: Do we really have to fonx the request if it was done with an 
-  old session ID?
-- Server capabilities: Keep hashing step for consistency or not? Extra request.
-- Client capabilities: List of hashes f.e device vs union of hashes on all 
-  devices?
-- Client capabilities: Clients which are offline but can be pushed should have 
-  their capabilities visible.
-  How to manage unregistering them e.g. if they uninstall the app?
-- What do server-generated events look like?
 - What do read-up-to markers look like?
-- Offline mode? How does that work with sessions?
-- Per device presence
 - Receiving events for unknown rooms. How do you handle this?
-- Linking the termination of typing events to the message itself, so you don't 
-  need to send
-  two events and don't get flicker.
-- Filtering: Blacklist (negative) filters? E.g. "don't give me 
-  ``event.type.here`` events
-- Public room list API
   
 Summary of changes from v1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -96,6 +85,9 @@ Excluded:
  
 Filter API
 ----------
+``ONGOING`` : Exactly what can be filtered? Which APIs use this? Are we 
+conflating too much?
+
 Inputs:
  - Which event types (incl wildcards)
  - Which room IDs
@@ -123,6 +115,8 @@ TODO:
 
 Global ``/initialSync`` API
 ---------------------------
+``ONGOING`` : See TODO section.
+
 Inputs:
  - A way of identifying the user (e.g. access token, user ID, etc)
  - Streaming token (optional)
@@ -209,6 +203,8 @@ What data flows does it address:
  
 Room Creation
 -------------
+``Draft``
+
 Inputs:
   - Invitee list of user IDs, public/private, state events to set on creation 
     e.g. name of room, alias of room, topic of room
@@ -221,6 +217,8 @@ What data flows does it address:
  
 Joining a room
 --------------
+``Draft``
+
 Inputs:
  - Room ID (with list of servers to join from) / room alias / invite event ID
  - Optional filter (which events to return, whether the returned events should 
@@ -251,11 +249,21 @@ Mapping messages to the event stream:
    clients, rather than annotating the join event. The server-generated event 
    works nicely for Application Services where an entity subscribes to a room 
    without a join event.
+ - This will look like an event for the room, but have a special 
+   "server-generated" event type e.g. ``m.homeserver.scrollback`` with a 
+   ``token`` containing the start token for the room.
 What data flows does it address:
  - Home Screen: Joining a room
  
 Scrolling back (infinite scrolling)
 -----------------------------------
+``Draft``
+
+.. NOTE::
+ - Pagination: Would be nice to have "and X more". It will probably be 
+   Google-style estimates given we can't know the exact number over federation, 
+   but as a purely informational display thing it would be nice.
+
 Inputs:
  - Identifier for the earliest event
  - # requested events
@@ -270,6 +278,8 @@ What data flows does it address:
  
 Contextual windowing
 --------------------
+``Draft``
+
 This refers to showing a "window" of message events around a given message 
 event. The window provides the "context" for the given message event.
 
@@ -322,6 +332,8 @@ fashion.
  
 Inviting a user
 ~~~~~~~~~~~~~~~
+``Final``
+
 Inputs:
  - User ID
  - Room ID
@@ -333,6 +345,8 @@ What data flows does it address:
  
 Rejecting an invite
 ~~~~~~~~~~~~~~~~~~~
+``Final``
+
 Inputs:
  - Event ID (to know which invite you're rejecting)
 Outputs:
@@ -343,8 +357,22 @@ Notes:
  - Rejecting an invite results in the ``m.room.member`` state event being 
    DELETEd for that user.
    
-Deleting a state event
+Sending state events
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
+``Final``
+
+Inputs:
+ - Event type
+ - State key
+ - Room ID
+ - Content
+Outputs:
+ - None.
+   
+Deleting state events
+~~~~~~~~~~~~~~~~~~~~~
+``Draft``
+
 Inputs:
  - Event type
  - State key
@@ -357,6 +385,8 @@ Notes:
  
 Kicking a user
 ~~~~~~~~~~~~~~
+``Final``
+
 Inputs:
  - User ID
  - Room ID
@@ -368,6 +398,8 @@ What data flows does it address:
 
 Leaving a room
 ~~~~~~~~~~~~~~
+``Final``
+
 Inputs:
  - Room ID
  - A way of identifying the user (user ID, access token)
@@ -379,6 +411,8 @@ What data flows does it address:
  
 Send a message
 ~~~~~~~~~~~~~~
+``ONGOING`` : Semantics for HTTP ordering.
+
 Inputs:
  - Room ID
  - Message contents
@@ -399,6 +433,11 @@ E2E Notes:
  
 Sessions
 --------
+``ONGOING``
+
+.. NOTE::
+ - Offline mode? How does that work with sessions?
+
 A session is a group of requests sent within a short amount of time by the same 
 client. Sessions time out after a short amount of time without any requests. 
 Starting a session is known as going "online". Its purpose is to wrap up the 
@@ -416,8 +455,14 @@ response for the client to use. If the client receives a new session ID
 mid-session, it must re-establish its typing status and presence status, as they
 are linked to the session ID.
 
-Presence
+Presence API
-~~~~~~~~
+------------
+``ONGOING``
+
+.. NOTE::
+ - Per device presence
+ - Presence lists / roster?
+
 When a session starts, the home server can treat the user as "online". When the 
 session ends, the home server can treat the user as "offline".
 
@@ -425,12 +470,16 @@ Inputs:
  - Presence state (online, offline, away, busy, do not disturb, etc)
 Outputs:
  - None.
-Notes:
- - TODO: Handle multiple devices.
 
 
-Typing
+Typing API
-~~~~~~
+----------
+``ONGOING``
+
+.. NOTE::
+ - Linking the termination of typing events to the message itself, so you don't 
+   need to send two events and don't get flicker.
+
 When in a session, a user can send a request stating that they are typing in a 
 room. They are no longer typing when either the session ends or they explicitly 
 send another request to say they are no longer typing.
@@ -444,7 +493,15 @@ Notes:
  - Typing will time out when the session ends.
  
 Action IDs
-~~~~~~~~~~
+----------
+``ONGOING``
+
+.. NOTE::
+ - HTTP Ordering: Blocking requests with higher seqnums is troublesome if there 
+   is a max # of concurrent connections a client can have open. 
+ - Session expiry: Do we really have to fonx the request if it was done with an 
+   old session ID?
+
 Action IDs are scoped per session. The first action ID for a session should be 
 0. For each subsequent action request, the ID should be incremented by 1. It 
 should be reset to 0 when a new session starts.
@@ -455,6 +512,8 @@ in order to avoid edge cases with incrementing action IDs.
 
 Updates (Events)
 ----------------
+``Draft``
+
 Events may update other events. This is represented by the ``updates`` key. This
 is a key which contains the event ID for the event it relates to. Events that 
 relate to other events are referred to as "Child Events". The event being 
@@ -498,6 +557,8 @@ needs to know how to combine the events.
 
 Relates to (Events)
 -------------------
+``Draft``
+
 Events may be in response to other events, e.g. comments. This is represented 
 by the ``relates_to`` key. This differs from the ``updates`` key as they *do 
 not update the event itself*, and are *not required* in order to display the 
@@ -528,7 +589,7 @@ TODO:
    e.g. can a HS retrieve all events for a given thread ID from another HS?
    
 Example using ``updates`` and ``relates_to``
----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Room with a single message.
 - 10 comments are added to the message via ``relates_to``.
 - An edit is made to the original message via ``updates``.
@@ -556,6 +617,8 @@ Example using ``updates`` and ``relates_to``
     
 Events (breaking changes; event version 2)
 ------------------------------------------
+``Draft``
+
 - Prefix the event ``type`` to say if it is a state event, message event or 
   ephemeral event. Needed because you can't tell the different between message 
   events and ephemeral ROOM events (e.g. typing).
@@ -573,8 +636,19 @@ Events (breaking changes; event version 2)
   the state key, etc.
 - s/user_id/sender/g given that home servers can send events, not just users.
 
-Capabilities
+Capabilities API
-------------
+----------------
+``ONGOING``
+
+.. NOTE::
+ - Server capabilities: Keep hashing step for consistency or not? Extra request.
+ - Client capabilities: List of hashes f.e device vs union of hashes on all 
+   devices?
+ - Client capabilities: Clients which are offline but can be pushed should have 
+   their capabilities visible. How to manage unregistering them e.g. if they 
+   uninstall the app?
+  
+
 How does a client know if the server it is using supports a content repository? 
 How does a client know if another client has VoIP support? This section outlines
 capability publishing for servers, clients and federation.