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

10 years ago · 760fc2e15b
parent 494a691a8c
commit 760fc2e15b
1 changed files with 133 additions and 59 deletions
--- a/drafts/general_api.rst
+++ b/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
- Global initial sync API
- Event stream API
- Room creation API
- Room joining API
- Scrollback API
- Contextual windowing API
+- Filtering API ``ONGOING``
+- Global initial sync API ``ONGOING``
+- Event stream API ``Draft``
+- Room creation API ``Draft``
+- Room joining API ``Draft``
+- Scrollback API ``Draft``
+- Contextual windowing API ``Draft``
 - Action APIs:
-   - Inviting
-   - Rejecting invites
-   - Leaving
-   - Kicking
-   - Banning
-   - Sending message events
-   - Sending state events
-   - Deleting state events
- Presence API
- Typing API
- Capabilities API
- ``TODO`` Room Directory API
- ``TODO`` Public room list API
- ``TODO`` User Profile API
+   - Inviting ``Final``
+   - Rejecting invites ``Final``
+   - Leaving ``Final``
+   - Kicking ``Final``
+   - Banning ``Final``
+   - Sending message events ``ONGOING``
+   - Sending state events ``Final``
+   - Deleting state events ``Draft``
+- Presence API ``ONGOING``
+- Typing API ``ONGOING``
+- Capabilities API ``ONGOING``
+- Room Directory API ``TODO``
+- Public room list API ``TODO``
+- 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
- Updates
- State key restrictions
- Event type rule setting
+- Action IDs ``ONGOING``
+- Sessions ``ONGOING``
+- Relates to ``Draft``
+- 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.