From 6904b2868ee7b68168e9a93e518f0da1a8368b00 Mon Sep 17 00:00:00 2001 From: Kegsay Date: Wed, 31 Dec 2014 12:36:56 +0000 Subject: [PATCH] Update general_api.rst Add info on smaller APIs / edge cases. --- drafts/general_api.rst | 79 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/drafts/general_api.rst b/drafts/general_api.rst index 0b8c5000..1644adad 100644 --- a/drafts/general_api.rst +++ b/drafts/general_api.rst @@ -1,5 +1,11 @@ Instant Messaging ================= + +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. Filter API ---------- @@ -7,6 +13,10 @@ Inputs: - Which event types (incl wildcards) - Which room IDs - Which user IDs (for profile/presence) + - Whether you want federation-style event JSON + - Whether you want coalesced ``updates`` events + - Whether you want coalesced ``in_reply_to`` events (and the max # to coalesce) + - limit= param? Outputs: - An opaque token which represents the inputs Notes: @@ -14,17 +24,31 @@ Notes: - The token could be as simple as a concatenation of the requested filters with a delimiter between them. - Omitting the token on APIs results in ALL THE THINGS coming down. - Clients should remember which token they need to use for which API. + - HTTP note: If the filter API is a separate endpoint, then you could easily allow APIs which use filtering + to ALSO specifiy query parameters to tweak the filter. Global ``/initialSync`` API --------------------------- Inputs: - A way of identifying the user (e.g. access token, user ID, etc) + - Streaming token (optional) - Filter to apply Outputs: - For each room the user is joined: Name, topic, # members, last message, room ID, aliases +Notes: + - If a streaming token is applied, you will get a delta rather than all the rooms. What data flows does it address: - Home screen: data required on load. +TODO: + - Will need some form of state event pagination like we have for message events to handle large + amounts of state events for a room. Need to think of the consequences of this: you may not get a + ``m.room.member`` for someone's message and so cannot display their display name / avatar. + - Handle paginating initial sync results themselves (e.g. 10 most recent rooms) + - No need for state events under the 'state' key to have a ``prev_content``. Can also apply some + optimisations depending on the direction of travel when scrolling back. + + Event Stream API ---------------- Inputs: @@ -53,6 +77,12 @@ Message Events Ordering Notes: where to insert it so that scrollback remains consistent and doesn't omit messages. - Clients can specify an input parameter stating that they wish to receive these out-of-order events. - The event, when it comes down the stream, will indicate which event it comes after. +Rejected events: + - A home server may find out via federation that it should not have accepted an event (e.g. to send a + message/state event in a room). + - If this happen, the home server will send a ``m.room.redaction`` for the event in question. + - If the event was a state event, it will synthesise a new state event to correct the client's room state. + - In practice, clients don't need any extra special handling for this. What data flows does it address: - Home Screen: Data required when new message arrives for a room - Home Screen: Data required when someone invites you to a room @@ -119,6 +149,18 @@ Outputs: What data flows does it address: - Chat Screen: Scrolling back (infinite scrolling) +Contextual messages +------------------- +Inputs: + - Event ID of the message to get the surrounding context for (this specifies the room to get messages in). + - Number of messages before/after this message to obtain. + - Filter to apply. +Outputs: + - Chunk of messages + - Start / End pagination tokens + - Current room state at the end of the chunk as per initial sync. + + Action APIs ----------- The following APIs are "action APIs". This is defined to be a request which alters the state of @@ -161,6 +203,25 @@ Outputs: What data flows does it address: - Chat Screen: Invite a user +Rejecting an invite +~~~~~~~~~~~~~~~~~~~ +Inputs: + - Event ID (to know which invite you're rejecting) +Outputs: + - None. +Notes: + - Giving the event ID rather than user ID/room ID combo because mutliple users can invite the + same user into the same room. + +Deleting a state event +~~~~~~~~~~~~~~~~~~~~~~ +Inputs: + - Event type + - State key + - Room ID +Outputs: + - None. + Kicking a user ~~~~~~~~~~~~~~ Inputs: @@ -194,6 +255,9 @@ Outputs: - When in the stream this action happened. (to correctly display local echo) What data flows does it address: - Chat Screen: Send a Message +E2E Notes: + - For signing: You send the original message to the HS and it will return the full event JSON which will + be sent. This full event is then signed and sent to the HS again to send the message. Sessions -------- @@ -333,6 +397,21 @@ Example using ``updates`` and ``in_reply_to`` ] } } + +Events (breaking changes; event version 2) +------------------------------------------ +- 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). +- State keys need additional restrictions in order to increase flexibility on state event permissions. + State keys prefixed with an ``_`` have no specific restrictions. 0-length state keys are now represented + by just a single ``_``. State keys prefixed with ``@`` can be modified only by the named user ID *OR* the + room ops. They can have an optional path suffixed to it. State keys that start with a server name can only + be modified by that server name (e.g. ``some.server.com/some/path`` can only be modified by + ``some.server.com``). +- Do we want to specify what restrictions apply to the state key in the event type? This would allow HSes + to enforce this, making life easier for clients when dealing with custom event types. E.g. ``_custom.event`` + would allow anything in the state key, ``_@custom.event`` would only allow user IDs in the state key, etc. + VoIP ----