From 2797fac3aa2a45049d3ee1932a7470fbb10b9c3e Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 9 Sep 2015 17:55:40 +0100 Subject: [PATCH 1/2] Swagger /room/{roomId}/invite This is a transcription of the current spec, with nothing new or controversial in it. --- api/client-server/v1/membership.yaml | 64 +++++++++++++++++++++++++- specification/10_client_server_api.rst | 33 ++----------- 2 files changed, 66 insertions(+), 31 deletions(-) diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index d847a78fb..86e84111e 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -48,7 +48,7 @@ paths: application/json: |- {"room_id": "!d41d8cd:matrix.org"} schema: - type: object # empty json object + type: 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: @@ -65,3 +65,65 @@ paths: canonical-link: "post-matrix-client-api-v1-rooms-roomid-join" aliases: - /join/{roomId} + + "/rooms/{roomId}/invite": + post: + summary: Invite a user to participate in a particular room. + # It's a crying shame that I don't know how to force line breaks. + description: |- + This API invites a user to participate in a particular room. + They do not start participating in the room until they actually join the + room. + + This serves two purposes; firstly, to notify the user that the room + exists (and that their presence is requested). Secondly, some rooms can + only be joined if a user is invited to join it; sending the invite gives + that user permission to join the room. + + Only users currently in a particular room can invite other users to + join that room. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier or room alias to which to invite the user. + required: true + x-example: "#monkeys:matrix.org" + - in: body + name: user_id + required: true + schema: + type: object + example: |- + { + "user_id": "@cheeky_monkey:matrix.org" + } + properties: + user_id: + type: string + description: The fully qualified user ID of the invitee. + required: ["user_id"] + responses: + 200: + description: The user has been invited to join the room. + examples: + application/json: |- + {} + schema: + type: object # empty json object + 403: + description: |- + You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are: + - The invitee has been banned from the room. + - The invitee is already a member of the room. + - The inviter is not currently in the room. + - The inviter's power level is insufficient to invite users to the room. + examples: + application/json: |- + {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" diff --git a/specification/10_client_server_api.rst b/specification/10_client_server_api.rst index 1fdb9ae6f..f0d6be42e 100644 --- a/specification/10_client_server_api.rst +++ b/specification/10_client_server_api.rst @@ -890,17 +890,9 @@ room. There are several states in which a user may be, in relation to a room: - Joined (the user can send and receive events in the room) - Banned (the user is not allowed to join the room) -{{membership_http_api}} - -Inviting users -~~~~~~~~~~~~~~ -.. TODO-doc Invite-join dance - - Outline invite join dance. What is it? Why is it required? How does it work? - - What does the home server have to do? +Some rooms require that users be invited to it before they can join; others +allow anyone to join. -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 -users who join a room are previously invited to it (an "invite-only" room). Whether a given room is an "invite-only" room is determined by the room config key ``m.room.join_rules``. It can have one of the following values: @@ -910,26 +902,7 @@ key ``m.room.join_rules``. It can have one of the following values: ``invite`` This room can only be joined if you were invited. -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 -entire invitation process:: - - { - "user_id": "" - } - -Alternatively, the membership state for this user in this room can be modified -directly by sending the following request to -``/rooms//state/m.room.member/``:: - - { - "membership": "invite" - } - -See the `Room events`_ section for more information on ``m.room.member``. +{{membership_http_api}} Leaving rooms ~~~~~~~~~~~~~ From a54814856357db32f2e430561a9e8fd5aa381024 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Thu, 10 Sep 2015 11:21:18 +0100 Subject: [PATCH 2/2] Invite doesn't accept room aliases --- api/client-server/v1/membership.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index 86e84111e..04922656d 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -88,9 +88,9 @@ paths: - in: path type: string name: roomId - description: The room identifier or room alias to which to invite the user. + description: The room identifier (not alias) to which to invite the user. required: true - x-example: "#monkeys:matrix.org" + x-example: "!d41d8cd:matrix.org" - in: body name: user_id required: true