incorporate feedback from reviewers

pull/977/head
Hubert Chathi 6 years ago
parent 5bc29eb11c
commit ce1e2c0904

@ -27,14 +27,13 @@ paths:
summary: Gets Matrix server discovery information about the domain.
description: |-
Gets discovery information about the domain. The file may include
additional keys, which SHOULD follow the Java package naming convention,
additional keys, which MUST follow the Java package naming convention,
e.g. ``com.example.myapp.property``. This ensures property names are
suitably namespaced for each application and reduces the risk of
clashes.
**FIXME:** do we need to add a note that this endpoint is not
necessarily handled by the homeserver, but by another webserver? Or
does the context make this clear enough?
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
responses:
200:
@ -55,8 +54,12 @@ paths:
description: Information about the homeserver to connect to.
"$ref": "definitions/wellknown/homeserver.yaml"
m.identity_server:
description: Information about the identity server to connect to.
description: Optional. Information about the identity server to connect to.
"$ref": "definitions/wellknown/identity_server.yaml"
additionalProperties:
description: Application-dependent keys using Java package naming convention.
required:
- m.homeserver
404:
description: No server discovery information available
tags:

@ -16,6 +16,10 @@ Unreleased changes
- Add sticker message event definition.
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
- Server discovery:
- Add ``.well-known`` discovery method
(`#1359 <https://github.com/matrix-org/matrix-doc/pull/1359>`_).
- Spec clarifications:
- Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions

@ -168,17 +168,17 @@ Server Discovery
~~~~~~~~~~~~~~~~
In order to allow users to connect to a Matrix server without needing to
explicitly specify the homeserver's URL or other parameters, clients may use an
auto-discovery mechanism to determine the server's URL based on a user's
Matrix ID. Auto-discovery should only be done at login time, with the
discovered values retained for the duration of the user's session.
explicitly specify the homeserver's URL or other parameters, clients SHOULD use
an auto-discovery mechanism to determine the server's URL based on a user's
Matrix ID. Auto-discovery should only be done at login time.
In this section, the following terms are used with specific meanings:
``PROMPT``
Retrieve the specific piece of information from the user in a way which
fits within the existing client UX, if the client is inclined to do so.
Failure can take place instead if no good UX is possible at this point.
fits within the existing client user experience, if the client is inclined to
do so. Failure can take place instead if no good user experience for this is
possible at this point.
``IGNORE``
Stop the current auto-discovery mechanism. If no more auto-discovery
@ -223,16 +223,19 @@ specify parameter values. The flow for this method is as follows:
e. Validate the homeserver base URL:
i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``.
ii. Clients should validate that the URL points to a valid homeserver
before accepting it. Currently, the suggested way of validating is
to connect to the ``/_matrix/client/versions`` endpoint, and to parse
and validate the data. If any step in the validation fails, then
``FAIL_ERROR``.
ii. Clients SHOULD validate that the URL points to a valid homeserver
before accepting it by connecting to the ``/_matrix/client/versions``
endpoint, and parsing and validating the data. If any step in the
validation fails, then ``FAIL_ERROR``. Validation is done as a simple
check against configuration errors, before sending sensitive
information such as a user's password to the server.
f. If the ``m.identity_server`` property is present, extract the
``base_url`` value for use as the base URL of the identity server. This
value can be validated as in the step above, but using
``/_matrix/identity/api/v1``.
``base_url`` value for use as the base URL of the identity server.
Validation for this URL is done as in the step above, but using
``/_matrix/identity/api/v1`` as the endpoint to connect to. If the
``m.identity_server`` property is present, but does not have a
``base_url`` value, then ``FAIL_ERROR``.
{{wellknown_cs_http_api}}

Loading…
Cancel
Save