Add server support discovery endpoint (#1733)
* Add server support discovery endpoint As per MSC1929. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> * Add changelog Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> * Fix example indentation Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> * Apply suggestions from code review Co-authored-by: Travis Ralston <travpc@gmail.com> * Fix line length Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> * Add link to definiton of Matrix User ID Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> * Fix copyright Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> * Remove HTTP from supported protocols Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> --------- Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr> Co-authored-by: Travis Ralston <travpc@gmail.com>travis/release-steps-update-mar192024
Kévin Commaille
1 month ago
committed by
GitHub
parent
575c84d431
commit
44c16918fd
@ -0,0 +1 @@
|
||||
Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929).
|
||||
@ -0,0 +1,135 @@
|
||||
# Copyright 2024 Kévin Commaille
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Support Discovery API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/matrix/support:
|
||||
get:
|
||||
summary: Gets homeserver contacts and support details.
|
||||
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
|
||||
GET request to `https://hostname/.well-known/matrix/support`.
|
||||
|
||||
Note that this endpoint is not necessarily handled by the homeserver.
|
||||
It may be served by another webserver, used for discovering support
|
||||
information for the homeserver.
|
||||
operationId: getWellknownSupport
|
||||
x-addedInMatrixVersion: "1.10"
|
||||
responses:
|
||||
"200":
|
||||
description: Server support information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
contacts:
|
||||
type: array
|
||||
description: |-
|
||||
Ways to contact the server administrator.
|
||||
|
||||
At least one of `contacts` or `support_page` is required.
|
||||
If only `contacts` is set, it must contain at least one
|
||||
item.
|
||||
items:
|
||||
type: object
|
||||
title: Contact
|
||||
description: A way to contact the server administrator.
|
||||
properties:
|
||||
matrix_id:
|
||||
type: string
|
||||
description: |-
|
||||
A [Matrix User ID](/appendices/#user-identifiers)
|
||||
representing the administrator.
|
||||
|
||||
It could be an account registered on a different
|
||||
homeserver so the administrator can be contacted
|
||||
when the homeserver is down.
|
||||
|
||||
At least one of `matrix_id` or `email_address` is
|
||||
required.
|
||||
email_address:
|
||||
type: string
|
||||
description: |-
|
||||
An email address to reach the administrator.
|
||||
|
||||
At least one of `matrix_id` or `email_address` is
|
||||
required.
|
||||
role:
|
||||
type: string
|
||||
enum:
|
||||
- "m.role.admin"
|
||||
- "m.role.security"
|
||||
description: |-
|
||||
An informal description of what the contact methods
|
||||
are used for.
|
||||
|
||||
`m.role.admin` is a catch-all role for any queries
|
||||
and `m.role.security` is intended for sensitive
|
||||
requests.
|
||||
|
||||
Unspecified roles are permitted through the use of
|
||||
[Namespaced Identifiers](/appendices/#common-namespaced-identifier-grammar).
|
||||
required:
|
||||
- role
|
||||
example: {
|
||||
"matrix_id": "@admin:example.org",
|
||||
"email_address": "admin@example.org",
|
||||
"role": "m.role.admin"
|
||||
}
|
||||
support_page:
|
||||
type: string
|
||||
description: |-
|
||||
The URL of a page to give users help specific to the
|
||||
homeserver, like extra login/registration steps.
|
||||
|
||||
At least one of `contacts` or `support_page` is required.
|
||||
example: "https://example.org/support.html"
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
{
|
||||
"contacts": [
|
||||
{
|
||||
"matrix_id": "@admin:example.org",
|
||||
"email_address": "admin@example.org",
|
||||
"role": "m.role.admin"
|
||||
},
|
||||
{
|
||||
"email_address": "security@example.org",
|
||||
"role": "m.role.security"
|
||||
}
|
||||
],
|
||||
"support_page": "https://example.org/support.html"
|
||||
}
|
||||
"404":
|
||||
description: No server support information available.
|
||||
tags:
|
||||
- Server administration
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /.well-known
|
||||
Loading…
Reference in New Issue