Improve documentation of directory API

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:

changelogs/client_server.rst

@@ -1,3 +1,13 @@
+<Unreleased changes>
+====================
+
+- 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
 ======
 

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}}