From 1e2b63763e5d7eedb7991031600655db251b59af Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 13 Jan 2016 15:55:51 +0000 Subject: [PATCH] /join and /room/:roomId/join aren't exact aliases Separate them, clarify their differences. Also, fix some links which weren't being properly populated. --- api/client-server/joining.yaml | 58 +++++++++++++++++-- specification/client_server_api.rst | 17 +++--- .../matrix_templates/templates/http-api.tmpl | 7 +-- templating/matrix_templates/units.py | 11 ---- 4 files changed, 63 insertions(+), 30 deletions(-) diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index 23bdc6a5..7b97409c 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -22,20 +22,70 @@ paths: post: summary: Start the requesting user participating in a particular room. description: |- + *Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.* + 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. + response of the |/initialSync|_ and |/sync|_ APIs. security: - accessToken: [] parameters: - in: path type: string name: roomId - description: The room identifier or room alias to join. + description: The room identifier (not alias) to join. + required: true + x-example: "!d41d8cd: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 + 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" + tags: + - Room membership + "/join/{roomIdOrAlias}": + post: + summary: Start the requesting user participating in a particular room. + description: |- + *Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``. + + 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|_ and |/sync|_ APIs. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomIdOrAlias + description: The room identifier or alias to join. required: true x-example: "#monkeys:matrix.org" responses: @@ -62,9 +112,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" - x-alias: - canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join" - aliases: - - /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId} tags: - Room membership diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 02d7eb9f..c9e6402c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -605,8 +605,8 @@ point in time:: Clients can add to the stream by PUTing message or state events, and can read from the stream via the -|initialSync|_, -|events|_, +|/initialSync|_, +|/events|_, |/rooms//initialSync|_, and |/rooms//messages|_ APIs. @@ -922,7 +922,7 @@ Leaving rooms A user can leave a room to stop receiving events for that room. A user must have been invited to or have joined the room before they are eligible to leave the room. Leaving a room to which the user has been invited rejects the invite. -Once a user leaves a room, it will no longer appear on the |initialSync|_ API. +Once a user leaves a room, it will no longer appear on the |/initialSync|_ API. Whether or not they actually joined the room, if the room is an "invite-only" room they will need to be re-invited before they can re-join @@ -1012,11 +1012,14 @@ have to wait in milliseconds before they can try again. .. Links through the external API docs are below .. ============================================= -.. |initialSync| replace:: ``/initialSync`` -.. _initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync +.. |/initialSync| replace:: ``/initialSync`` +.. _/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync -.. |events| replace:: ``/events`` -.. _events: #get-matrix-client-%CLIENT_MAJOR_VERSION%-events +.. |/sync| replace:: ``/sync`` +.. _/sync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-sync + +.. |/events| replace:: ``/events`` +.. _/events: #get-matrix-client-%CLIENT_MAJOR_VERSION%-events .. |/rooms//initialSync| replace:: ``/rooms//initialSync`` .. _/rooms//initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl index 27d3ddc9..adecd5d2 100644 --- a/templating/matrix_templates/templates/http-api.tmpl +++ b/templating/matrix_templates/templates/http-api.tmpl @@ -7,11 +7,6 @@ This API is deprecated and will be removed from a future release. {% endif -%} -{% if "alias_for_path" in endpoint -%} -``{{endpoint.path}}`` is an alias for `{{endpoint.alias_for_path}}`_. - -.. _`{{endpoint.alias_for_path}}`: #{{endpoint.alias_link}} -{% else -%} {{endpoint.desc | wrap(80)}} @@ -67,4 +62,4 @@ Example {{res["example"] | indent_block(2)}} {% endfor %} -{% endif -%} + diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 2d225adb..013a0b10 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -440,17 +440,6 @@ class MatrixUnits(Units): endpoints.append(endpoint) - aliases = single_api.get("x-alias", None) - if aliases: - alias_link = aliases["canonical-link"] - for alias in aliases["aliases"]: - endpoints.append({ - "method": method.upper(), - "path": alias, - "alias_for_path": full_path, - "alias_link": alias_link - }) - return { "base": api.get("basePath").rstrip("/"), "group": group_name,