diff --git a/changelogs/client_server/newsfragments/2140.clarification b/changelogs/client_server/newsfragments/2140.clarification new file mode 100644 index 00000000..4a151fe8 --- /dev/null +++ b/changelogs/client_server/newsfragments/2140.clarification @@ -0,0 +1 @@ +Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. diff --git a/changelogs/server_server/newsfragments/2140.clarification b/changelogs/server_server/newsfragments/2140.clarification new file mode 100644 index 00000000..4a151fe8 --- /dev/null +++ b/changelogs/server_server/newsfragments/2140.clarification @@ -0,0 +1 @@ +Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 94dfe35f..f2de85de 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -371,15 +371,23 @@ 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 URI +### 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. {{% 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 `.well-known` method uses a JSON file at a predetermined location to -specify parameter values. The flow for this method is as follows: +The flow for auto-discovery 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. @@ -415,10 +423,17 @@ specify parameter values. The flow for this method is as follows: {{% http-api spec="client-server" api="wellknown" %}} -{{% http-api spec="client-server" api="versions" %}} - {{% 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" %}} + ## Client Authentication Most API endpoints require the user to identify themselves by presenting diff --git a/content/server-server-api.md b/content/server-server-api.md index c82e3bee..10d91468 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -119,7 +119,8 @@ 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:///.well-known/matrix/server`, expecting + made to `https:///.well-known/matrix/server` (according to + [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)), 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 diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index b9ca062e..154afbe7 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -22,9 +22,12 @@ paths: description: |- Gets server admin contact and support page of the domain. - 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 + {{% 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 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 diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 72de3598..4e2383bf 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -26,6 +26,12 @@ 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 diff --git a/data/api/server-server/wellknown.yaml b/data/api/server-server/wellknown.yaml index 717462f9..920bc356 100644 --- a/data/api/server-server/wellknown.yaml +++ b/data/api/server-server/wellknown.yaml @@ -24,6 +24,12 @@ 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":