diff options
Diffstat (limited to 'docs/specification.rst')
| -rw-r--r-- | docs/specification.rst | 84 |
1 files changed, 53 insertions, 31 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index 3c6ed6b1c0..76a6eb0f76 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -134,8 +134,8 @@ Identity API Standards ------------- All communication in Matrix is performed over HTTP[S] using a Content-Type of ``application/json``. -Any errors which occur on the Matrix API level MUST return a "standard error response". This is a -JSON object which looks like:: +In addition, all strings MUST be encoded as UTF-8. Any errors which occur on the Matrix API level +MUST return a "standard error response". This is a JSON object which looks like:: { "errcode": "<error code>", @@ -219,22 +219,16 @@ In contrast, these are invalid requests:: "key": "This is a put but it is missing a txnId." } - - -- TODO: All strings everywhere are UTF-8 - - - Receiving live updates on a client ---------------------------------- Clients can receive new events by long-polling the home server. This will hold open the HTTP connection for a short period of time waiting for new events, returning early if an -event occurs. This is called the "Event Stream". All events which the client is authorised +event occurs. This is called the `Event Stream`_. All events which the client is authorised to view will appear in the event stream. When the stream is closed, an ``end`` token is returned. This token can be used in the next request to continue where the client left off. When the client first logs in, they will need to initially synchronise with their home -server. This is achieved via the ``/initialSync`` API. This API also returns an ``end`` +server. This is achieved via the |initialSync|_ API. This API also returns an ``end`` token which can be used with the event stream. Rooms @@ -242,7 +236,11 @@ Rooms Creation -------- -To create a room, a client has to use the ``/createRoom`` API. There are various options +.. TODO kegan + - TODO: This creates a room creation event which serves as the root of the PDU graph for this room. + - TODO: Key for invite these users? + +To create a room, a client has to use the |createRoom|_ API. There are various options which can be set when creating a room: ``visibility`` @@ -300,9 +298,6 @@ Example:: "topic": "All about happy hour" } -- TODO: This creates a room creation event which serves as the root of the PDU graph for this room. -- TODO: Key for invite these users? - Modifying aliases ----------------- .. NOTE:: @@ -329,7 +324,8 @@ Permissions Joining rooms ------------- -- TODO: What does the home server have to do to join a user to a room? +.. TODO kegan + - TODO: What does the home server have to do to join a user to a room? Users need to join a room in order to send and receive events in that room. A user can join a room by making a request to ``/join/<room alias or id>`` with:: @@ -356,16 +352,17 @@ by sending the following request to See the `Room events`_ section for more information on ``m.room.member``. After the user has joined a room, they will receive subsequent events in that room. This room -will now appear as an entry in the ``/initialSync`` API. +will now appear as an entry in the |initialSync|_ API. Some rooms enforce that a user is *invited* to a room before they can join that room. Other rooms will allow anyone to join the room even if they have not received an invite. Inviting users -------------- -- Can invite users to a room if the room config key TODO is set to TODO. Must have required power level. -- Outline invite join dance. What is it? Why is it required? How does it work? -- What does the home server have to do? +.. TODO kegan + - Can invite users to a room if the room config key TODO is set to TODO. Must have required power level. + - Outline invite join dance. What is it? Why is it required? How does it work? + - What does the home server have to do? The purpose of inviting users to a room is to notify them that the room exists so they can choose to become a member of that room. Some rooms require that all @@ -401,6 +398,11 @@ See the `Room events`_ section for more information on ``m.room.member``. Leaving rooms ------------- +.. TODO kegan + - TODO: Grace period before deletion? + - TODO: Under what conditions should a room NOT be purged? + + A user can leave a room to stop receiving events for that room. A user must have joined the room before they are eligible to leave the room. If the room is an "invite-only" room, they will need to be re-invited before they can re-join the room. @@ -418,7 +420,7 @@ directly by sending the following request to See the `Room events`_ section for more information on ``m.room.member``. -Once a user has left a room, that room will no longer appear on the ``/initialSync`` +Once a user has left a room, that room will no longer appear on the |initialSync|_ API. Be aware that leaving a room is not equivalent to have never been in that room. A user who has previously left a room still maintains some residual state in that room. Their membership state will be marked as ``leave``. This contrasts with @@ -426,12 +428,9 @@ a user who has *never been invited or joined to that room* who will not have any membership state for that room. If all members in a room leave, that room becomes eligible for deletion. - - TODO: Grace period before deletion? - - TODO: Under what conditions should a room NOT be purged? Banning users in a room ----------------------- - A user may decide to ban another user in a room. 'Banning' forces the target user to leave the room and prevents them from re-joining the room. A banned user will not be treated as a joined user, and so will not be able to send or receive events @@ -533,19 +532,23 @@ See `Room Events`_ for the ``m.`` event specification. Syncing rooms ------------- +.. NOTE:: + This section is a work in progress. + When a client logs in, they may have a list of rooms which they have already joined. These rooms may also have a list of events associated with them. The purpose of 'syncing' is to present the current room and event information in a convenient, compact manner. The events returned are not limited to room events; presence events will also be returned. There are two APIs provided: - - ``/initialSync`` : A global sync which will present room and event information for all rooms + - |initialSync|_ : A global sync which will present room and event information for all rooms the user has joined. - - ``/rooms/<room id>/initialSync`` : A sync scoped to a single room. Presents room and event + - |roomInitialSync|_ : A sync scoped to a single room. Presents room and event information for this room only. -- TODO: JSON response format for both types -- TODO: when would you use global? when would you use scoped? +.. TODO kegan + - TODO: JSON response format for both types + - TODO: when would you use global? when would you use scoped? Getting events for a room ------------------------- @@ -584,7 +587,7 @@ There are several APIs provided to ``GET`` events for a room: Example: TODO -``/rooms/<room id>/initialSync`` +|roomInitialSync|_ Description: Get all relevant events for a room. This includes state events, paginated non-state events and presence events. @@ -851,6 +854,9 @@ user was last seen online. Transmission ------------ +.. NOTE:: + This section is a work in progress. + .. TODO: - Transmitted as an EDU. - Presence lists determine who to send to. @@ -933,8 +939,9 @@ Registration and login .. WARNING:: The registration API is likely to change. -- TODO Kegan : Make registration like login (just omit the "user" key on the - initial request?) +.. TODO + - TODO Kegan : Make registration like login (just omit the "user" key on the + initial request?) Clients must register with a home server in order to use Matrix. After registering, the client will be given an access token which must be used in ALL @@ -946,7 +953,8 @@ as user/password auth, login via a social network (OAuth2), login by confirming a token sent to their email address, etc. This specification does not define how home servers should authorise their users who want to login to their existing accounts, but instead defines the standard interface which implementations -should follow so that ANY client can login to ANY home server. +should follow so that ANY client can login to ANY home server. Clients login +using the |login|_ API. The login process breaks down into the following: 1. Determine the requirements for logging in. @@ -1444,3 +1452,17 @@ User ID: An opaque ID which identifies an end-user, which consists of some opaque localpart combined with the domain name of their home server. +.. |createRoom| replace:: ``/createRoom`` +.. _createRoom: /-rooms/create_room + +.. |initialSync| replace:: ``/initialSync`` +.. _initialSync: /-events/initial_sync + +.. |roomInitialSync| replace:: ``/rooms/<room id>/initialSync`` +.. _roomInitialSync: /-rooms/get_room_sync_data + +.. |login| replace:: ``/login`` +.. _login: /-login + +.. _`Event Stream`: /-events/get_event_stream +.. _`Initial Sync`: /-events/initial_sync |