Merge pull request #33 from matrix-org/daniel/threepidinvites

Spec /room/{roomId}/join

api/client-server/v1/membership.yaml

@@ -0,0 +1,67 @@
+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:
+  "/rooms/{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.
+
+        After a user has joined a room, the room will appear as an entry in the
+        response of the |initialSync| API.
+      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.
+
+            The joined room ID must be returned in the ``room_id`` field.
+          examples:
+            application/json: |-
+              {"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:
+              - 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"
+      x-alias:
+        canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
+        aliases:
+          - /join/{roomId}

specification/10_client_server_api.rst

@@ -879,44 +879,18 @@ 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
-~~~~~~~~~~~~~
-.. 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/<room_alias_or_id>|_ with::
-
-  {}
-
-Alternatively, a user can make a request to |/rooms/<room_id>/join|_ with the
-same request content.  This is only provided for symmetry with the other
-membership APIs: ``/rooms/<room id>/invite`` and ``/rooms/<room id>/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/<room id>/state/m.room.member/<url encoded user id>``::
-
-  {
-    "membership": "join"
-  }
-
-See the `Room events`_ section for more information on ``m.room.member``.
+-------------
+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:
 
-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.
+ - 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)
 
-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
 ~~~~~~~~~~~~~~

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 (