diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index 226801453..0382acec7 100644 --- a/api/client-server/directory.yaml +++ b/api/client-server/directory.yaml @@ -48,10 +48,25 @@ paths: {} schema: type: object + 409: + description: A room alias with that name already exists. + examples: + application/json: |- + { + "errcode": "M_UNKNOWN", + "error": "Room alias #monkeys:matrix.org already exists." + } tags: - Room directory get: summary: Get the room ID corresponding to this room alias. + description: |- + Requests that the server resolve a room alias to a room ID. + + The server will use the federation API to resolve the alias if the + domain part of the alias does not correspond to the server's own + domain. + parameters: - in: path type: string @@ -92,14 +107,6 @@ paths: "errcode": "M_NOT_FOUND", "error": "Room ID !abnjk1jdasj98:capuchins.com not found." } - 409: - description: A room alias with that name already exists. - examples: - application/json: |- - { - "errcode": "M_UNKNOWN", - "error": "Room alias #monkeys:matrix.org already exists." - } tags: - Room directory delete: diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index dee91c709..ae2736f20 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -1,3 +1,13 @@ + +==================== + +- Spec clarifications + + - Make it clear that ``GET /directory/room/{roomAlias}`` must work for + federated aliases + - ``GET /directory/room/{roomAlias}`` cannot return a 409; the ``PUT`` + endpoint can, however. + r0.1.0 ====== diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6ae6a1371..901369c3e 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -925,7 +925,9 @@ form ``#friendlyname:server.name``. As room aliases are scoped to a particular homeserver domain name, it is likely that a homeserver will reject attempts to maintain aliases on other domain names. This specification does not provide a way for homeservers to -send update requests to other servers. +send update requests to other servers. However, homeservers MUST handle +``GET`` requests to resolve aliases on other servers; they should do this using +the federation API if necessary. Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state event. This alias list is partial because it cannot guarantee that the alias @@ -937,9 +939,6 @@ appears to have a room alias of ``#alias:example.com``, this SHOULD be checked to make sure that the room's ID matches the ``room_id`` returned from the request. -Homeservers can respond to resolve requests for aliases on other domains than -their own by using the federation API to ask other domain name homeservers. - {{directory_cs_http_api}}