Merge 110ae95ce8 into fe46e0c363

changelogs/client_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

changelogs/server_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

content/client-server-api/_index.md

@@ -371,23 +371,15 @@ valid data was obtained, but no server is available to serve the client.
 No further guess should be attempted and the user should make a
 conscientious decision what to do next.
 
-### Well-known URIs
-
-Matrix facilitates automatic discovery for the Client-Server API base URL and more via the
-[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) "Well-Known URI" method.
-This method uses JSON files at a predetermined location on the root path `/.well-known/` to
-specify parameter values.
+### Well-known URI
 
 {{% boxes/note %}}
-Diverging from the rest of the endpoints in the Client-Server spec, these files can not be provided
-on the base URL that the Client-Server API is reachable on, as it is yet to be discovered.
-Instead, they can be reached via HTTPS on the [server name](/appendices/#server-name)'s hostname as domain.
-
 Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
 as per the [CORS](#web-browser-clients) section in this specification.
 {{% /boxes/note %}}
 
-The flow for auto-discovery is as follows:
+The `.well-known` method uses a JSON file at a predetermined location to
+specify parameter values. The flow for this method is as follows:
 
 1.  Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
     Matrix ID at the first colon.
@@ -423,17 +415,10 @@ The flow for auto-discovery is as follows:
 
 {{% http-api spec="client-server" api="wellknown" %}}
 
-{{% http-api spec="client-server" api="support" %}}
-
-### API Versions
-
-Upon connecting, the Matrix client and server need to negotiate which version of the specification
-they commonly support, as the API evolves over time. The server advertises its supported versions
-and optionally unstable features to the client, which can then go on to make requests to the
-endpoints it supports.
-
 {{% http-api spec="client-server" api="versions" %}}
 
+{{% http-api spec="client-server" api="support" %}}
+
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting

content/server-server-api.md

@@ -119,8 +119,7 @@ to send. The process overall is as follows:
     server must present a valid certificate for the hostname.
 
 3.  If the hostname is not an IP literal, a regular HTTPS request is
-    made to `https://<hostname>/.well-known/matrix/server` (according to 
-    [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)), expecting
+    made to `https://<hostname>/.well-known/matrix/server`, expecting
     the schema defined later in this section. 30x redirects should be
     followed, however redirection loops should be avoided. Responses
     (successful or otherwise) to the `/.well-known` endpoint should be

data/api/client-server/support.yaml

@@ -22,12 +22,9 @@ paths:
       description: |-
         Gets server admin contact and support page of the domain.
 
-        {{% boxes/note %}}
-        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
-        this endpoint should be accessed with the hostname of the homeserver's
-        [server name](/appendices/#server-name) by making a
+        Like the [well-known discovery URI](/client-server-api/#well-known-uri),
+        this should be accessed with the hostname of the homeserver by making a
         GET request to `https://hostname/.well-known/matrix/support`.
-        {{% /boxes/note %}}
 
         Note that this endpoint is not necessarily handled by the homeserver.
         It may be served by another webserver, used for discovering support

data/api/client-server/wellknown.yaml

@@ -26,12 +26,6 @@ paths:
         suitably namespaced for each application and reduces the risk of
         clashes.
 
-        {{% boxes/note %}}
-        This endpoint should be accessed with the hostname of the homeserver's
-        [server name](/appendices/#server-name) by making a
-        GET request to `https://hostname/.well-known/matrix/client`.
-        {{% /boxes/note %}}
-
         Note that this endpoint is not necessarily handled by the homeserver,
         but by another webserver, to be used for discovering the homeserver URL.
       operationId: getWellknown

data/api/server-server/wellknown.yaml

@@ -24,12 +24,6 @@ paths:
         Gets information about the delegated server for server-server communication
         between Matrix homeservers. Servers should follow 30x redirects, carefully
         avoiding redirect loops, and use normal X.509 certificate validation.
-
-        {{% boxes/note %}}
-        This endpoint should be accessed with the hostname of the homeserver's
-        [server name](/appendices/#server-name) by making a
-        GET request to `https://hostname/.well-known/matrix/server`.
-        {{% /boxes/note %}}
       operationId: getWellKnown
       responses:
         "200":