From d53943c8c2aa266d894d7fa0b5a2a3a8545f5c25 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 8 Sep 2015 16:35:08 +0100 Subject: [PATCH 1/4] Spec /room/{roomId}/join This is just replacing the existing spec with a swagger version. Subsequent pull requests will add 3pid join to this, as well as specing the invite, leave, ban, and kick endpoints. --- api/client-server/v1/membership.yaml | 68 +++++++++++++++++++++++++ specification/10_client_server_api.rst | 38 +------------- templating/matrix_templates/sections.py | 6 +++ 3 files changed, 75 insertions(+), 37 deletions(-) create mode 100644 api/client-server/v1/membership.yaml diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml new file mode 100644 index 000000000..24f3835df --- /dev/null +++ b/api/client-server/v1/membership.yaml @@ -0,0 +1,68 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v1 Room Membership API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + accessToken: + type: apiKey + description: The user_id or application service access_token + name: access_token + in: query +paths: + "/room/{roomId}/join": + post: + summary: Start the requesting user participating in a particular room. + description: |- + This API starts a user participating in a particular room, if that user + is allowed to participate in that room. After this call, the client is + allowed to see all current state events in the room, and all subsequent + events associated with the room until the user leaves the room. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier or room alias to join. + required: true + x-example: "#monkeys:matrix.org" + responses: + 200: + description: |- + The room has been joined. + + If the room was joined with an room alias, rather than a room ID, + the room ID must be returned in the room_id field. + + If the room was joined with a room ID, the room_id field must not be + present. + examples: + application/json: |- + {"room_id": "!primates:matrix.org"} + schema: + type: object # empty json object + 403: + description: |- + You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are: + - The room is invite-only and the user was not invited. + - The user has been banned from the room. + examples: + application/json: |- + {"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + "/join/{roomId}": + post: + x-alias-for-path: "/room/{roomId}/join" + x-alias-link: "post-matrix-client-api-v1-room-roomid-join" diff --git a/specification/10_client_server_api.rst b/specification/10_client_server_api.rst index 83c8b7a89..d0942ad67 100644 --- a/specification/10_client_server_api.rst +++ b/specification/10_client_server_api.rst @@ -880,43 +880,7 @@ certain operations such as kicking, banning and sending state events. See `m.room.power_levels`_ for more information. -Joining rooms -~~~~~~~~~~~~~ -.. TODO-doc What does the home server have to do to join a user to a room? - - See SPEC-30. - -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:: - - {} - -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:: - - { - "room_id": "!roomid:domain" - } - -The membership state for the joining user can also be modified directly to be -``join`` by sending the following request to -``/rooms//state/m.room.member/``:: - - { - "membership": "join" - } - -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. - -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. +{{membership_http_api}} Inviting users ~~~~~~~~~~~~~~ diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py index 7bc250952..7e21434f7 100644 --- a/templating/matrix_templates/sections.py +++ b/templating/matrix_templates/sections.py @@ -90,6 +90,12 @@ class MatrixSections(Sections): title_kind="~" ) + def render_membership_http_api(self): + return self._render_http_api_group( + "membership", + title_kind="~" + ) + def render_room_events(self): def filterFn(eventType): return ( From 1feb9565e4727f9c7c10619b84bb5f77976dd513 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 8 Sep 2015 16:51:39 +0100 Subject: [PATCH 2/4] Use other-way-around alias format --- api/client-server/v1/membership.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index 24f3835df..1845ce095 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -62,7 +62,6 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" - "/join/{roomId}": - post: - x-alias-for-path: "/room/{roomId}/join" + x-aliases: + - /join/{roomId} x-alias-link: "post-matrix-client-api-v1-room-roomid-join" From 04b2b2588f1453fb62d9e86277b0f2cefc5a6207 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 9 Sep 2015 13:18:23 +0100 Subject: [PATCH 3/4] Fix up formatting and typos --- api/client-server/v1/membership.yaml | 22 +++++++++++----------- specification/10_client_server_api.rst | 10 ++++++++++ 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index 1845ce095..b86e8b033 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -18,7 +18,7 @@ securityDefinitions: name: access_token in: query paths: - "/room/{roomId}/join": + "/rooms/{roomId}/join": post: summary: Start the requesting user participating in a particular room. description: |- @@ -26,6 +26,9 @@ paths: is allowed to participate in that room. After this call, the client is allowed to see all current state events in the room, and all subsequent events associated with the room until the user leaves the room. + + After a user has joined a room, the room will appear as an entry in the + response of the |initialSync| API. security: - accessToken: [] parameters: @@ -40,19 +43,15 @@ paths: description: |- The room has been joined. - If the room was joined with an room alias, rather than a room ID, - the room ID must be returned in the room_id field. - - If the room was joined with a room ID, the room_id field must not be - present. + The joined room ID must be returned in the room_id field. examples: application/json: |- - {"room_id": "!primates:matrix.org"} + {"room_id": "!d41d8cd:matrix.org"} schema: type: object # empty json object 403: description: |- - You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are: + You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are: - The room is invite-only and the user was not invited. - The user has been banned from the room. examples: @@ -62,6 +61,7 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" - x-aliases: - - /join/{roomId} - x-alias-link: "post-matrix-client-api-v1-room-roomid-join" + x-alias: + canonical-link: "post-matrix-client-api-v1-rooms-roomid-join" + aliases: + - /join/{roomId} diff --git a/specification/10_client_server_api.rst b/specification/10_client_server_api.rst index d0942ad67..1fdb9ae6f 100644 --- a/specification/10_client_server_api.rst +++ b/specification/10_client_server_api.rst @@ -879,6 +879,16 @@ The keys contained in ``m.room.power_levels`` determine the levels required for certain operations such as kicking, banning and sending state events. See `m.room.power_levels`_ for more information. +Joining rooms +------------- +Users need to be a member of a room in order to send and receive events in that +room. There are several states in which a user may be, in relation to a room: + + - Unrelated (the user cannot send or receive events in the room) + - Invited (the user has been invited to participate in the room, but is not + yet participating) + - Joined (the user can send and receive events in the room) + - Banned (the user is not allowed to join the room) {{membership_http_api}} From 1b591a023ecc5a167d630a6e1dad88981edcfefc Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 9 Sep 2015 14:04:48 +0100 Subject: [PATCH 4/4] Monospace room_id --- api/client-server/v1/membership.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index b86e8b033..d847a78fb 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -43,7 +43,7 @@ paths: description: |- The room has been joined. - The joined room ID must be returned in the room_id field. + The joined room ID must be returned in the ``room_id`` field. examples: application/json: |- {"room_id": "!d41d8cd:matrix.org"}