diff --git a/docs/specification.rst b/docs/specification.rst index 76a6eb0f7..0ef18aab6 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -328,11 +328,11 @@ Joining rooms - 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/`` with:: +room by making a request to |/join/|_ with:: {} -Alternatively, a user can make a request to ``/rooms//join`` with the same request content. +Alternatively, a user can make a request to |/rooms//join|_ with the same request content. This is only provided for symmetry with the other membership APIs: ``/rooms//invite`` and ``/rooms//leave``. If a room alias was specified, it will be automatically resolved to a room ID, which will then be joined. The room ID that was joined will be returned in response:: @@ -363,6 +363,7 @@ 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: In what circumstances will direct member editing NOT be equivalent to ``/invite``? 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 @@ -377,7 +378,7 @@ Only users who have a membership state of ``join`` in a room can invite new users to said room. The person being invited must not be in the ``join`` state in the room. The fully-qualified user ID must be specified when inviting a user, as the user may reside on a different home server. To invite a user, send the -following request to ``/rooms//invite``, which will manage the +following request to |/rooms//invite|_, which will manage the entire invitation process:: { @@ -394,8 +395,6 @@ directly by sending the following request to See the `Room events`_ section for more information on ``m.room.member``. -- TODO: In what circumstances will this NOT be equivalent to ``/invite``? - Leaving rooms ------------- .. TODO kegan @@ -406,7 +405,7 @@ Leaving rooms 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. -To leave a room, a request should be made to ``/rooms//leave`` with:: +To leave a room, a request should be made to |/rooms//leave|_ with:: {} @@ -436,7 +435,7 @@ 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 in the room. In order to ban someone, the user performing the ban MUST have the required power level. To ban a user, a request should be made to -``/rooms//ban`` with:: +|/rooms//ban|_ with:: { "user_id": "/state//``. +State events can be sent by ``PUT`` ing to |/rooms//state//|_. These events will be overwritten if ````, ```` and ```` all match. If the state event has no ``state_key``, it can be omitted from the path. These requests **cannot use transaction IDs** like other ``PUT`` paths because they cannot be differentiated @@ -517,7 +516,7 @@ See `Room Events`_ for the ``m.`` event specification. Non-state events ---------------- -Non-state events can be sent by sending a request to ``/rooms//send/``. +Non-state events can be sent by sending a request to |/rooms//send/|_. These requests *can* use transaction IDs and ``PUT``/``POST`` methods. Non-state events allow access to historical events and pagination, making it best suited for sending messages. For example:: @@ -543,7 +542,7 @@ limited to room events; presence events will also be returned. There are two API - |initialSync|_ : A global sync which will present room and event information for all rooms the user has joined. - - |roomInitialSync|_ : A sync scoped to a single room. Presents room and event + - |/rooms//initialSync|_ : A sync scoped to a single room. Presents room and event information for this room only. .. TODO kegan @@ -562,7 +561,7 @@ There are several APIs provided to ``GET`` events for a room: Example: ``/rooms/!room:domain.com/state/m.room.name`` returns ``{ "name": "Room name" }`` -``/rooms//state`` +|/rooms//state|_ Description: Get all state events for a room. Response format: @@ -571,7 +570,7 @@ There are several APIs provided to ``GET`` events for a room: TODO -``/rooms//members`` +|/rooms//members|_ Description: Get all ``m.room.member`` state events. Response format: @@ -579,7 +578,7 @@ There are several APIs provided to ``GET`` events for a room: Example: TODO -``/rooms//messages`` +|/rooms//messages|_ Description: Get all ``m.room.message`` events. Response format: @@ -587,7 +586,7 @@ There are several APIs provided to ``GET`` events for a room: Example: TODO -|roomInitialSync|_ +|/rooms//initialSync|_ Description: Get all relevant events for a room. This includes state events, paginated non-state events and presence events. @@ -622,7 +621,7 @@ prefixed with ``m.`` human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not *unique*, as multiple rooms can have the same room name set. The room name can also be set when - creating a room using ``/createRoom`` with the ``name`` key. + creating a room using |createRoom|_ with the ``name`` key. ``m.room.topic`` Summary: @@ -636,7 +635,8 @@ prefixed with ``m.`` Description: A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may - not be suitable for the room name. + not be suitable for the room name. The room topic can also be set when creating a + room using |createRoom|_ with the ``topic`` key. ``m.room.member`` Summary: @@ -1452,17 +1452,51 @@ 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. + +.. Links through the external API docs are below +.. ============================================= + .. |createRoom| replace:: ``/createRoom`` .. _createRoom: /-rooms/create_room .. |initialSync| replace:: ``/initialSync`` .. _initialSync: /-events/initial_sync -.. |roomInitialSync| replace:: ``/rooms//initialSync`` -.. _roomInitialSync: /-rooms/get_room_sync_data +.. |/rooms//initialSync| replace:: ``/rooms//initialSync`` +.. _/rooms//initialSync: /-rooms/get_room_sync_data .. |login| replace:: ``/login`` .. _login: /-login +.. |/rooms//messages| replace:: ``/rooms//messages`` +.. _/rooms//messages: /-rooms/get_messages + +.. |/rooms//members| replace:: ``/rooms//members`` +.. _/rooms//members: /-rooms/get_members + +.. |/rooms//state| replace:: ``/rooms//state`` +.. _/rooms//state: /-rooms/get_state_events + +.. |/rooms//send/| replace:: ``/rooms//send/`` +.. _/rooms//send/: /-rooms/send_non_state_event + +.. |/rooms//state//| replace:: ``/rooms//state//`` +.. _/rooms//state//: /-rooms/send_state_event + +.. |/rooms//invite| replace:: ``/rooms//invite`` +.. _/rooms//invite: /-rooms/invite + +.. |/rooms//join| replace:: ``/rooms//join`` +.. _/rooms//join: /-rooms/join_room + +.. |/rooms//leave| replace:: ``/rooms//leave`` +.. _/rooms//leave: /-rooms/leave + +.. |/rooms//ban| replace:: ``/rooms//ban`` +.. _/rooms//ban: /-rooms/ban + +.. |/join/| replace:: ``/join/`` +.. _/join/: /-rooms/join + .. _`Event Stream`: /-events/get_event_stream .. _`Initial Sync`: /-events/initial_sync