You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
220 lines
7.9 KiB
YAML
220 lines
7.9 KiB
YAML
# Copyright 2017 Kamax.io
|
|
# Copyright 2018 New Vector Ltd
|
|
#
|
|
# 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 Federation Query API
|
|
version: 1.0.0
|
|
paths:
|
|
"/query/{queryType}":
|
|
get:
|
|
summary: Query for information
|
|
description: |-
|
|
Performs a single query request on the receiving homeserver. The query string
|
|
arguments are dependent on which type of query is being made. Known query types
|
|
are specified as their own endpoints as an extension to this definition.
|
|
operationId: queryInfo
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: path
|
|
name: queryType
|
|
description: The type of query to make
|
|
required: true
|
|
example: profile
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: The query response. The schema varies depending on the query being
|
|
made.
|
|
/query/directory:
|
|
get:
|
|
summary: Query for the room ID and resident homeservers for a room alias
|
|
description: |-
|
|
Performs a query to get the mapped room ID and list of resident homeservers in
|
|
the room for a given room alias. Homeservers should only query room aliases
|
|
that belong to the target server (identified by the [server name](/appendices/#server-name)
|
|
in the alias).
|
|
|
|
Servers may wish to cache the response to this query to avoid requesting the
|
|
information too often.
|
|
operationId: queryRoomDirectory
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: query
|
|
name: room_alias
|
|
description: The room alias to query.
|
|
required: true
|
|
example: "#room_alias:example.org"
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: The corresponding room ID and list of known resident homeservers
|
|
for the room.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
room_id:
|
|
type: string
|
|
description: The room ID mapped to the queried room alias.
|
|
example: "!roomid1234:example.org"
|
|
servers:
|
|
type: array
|
|
description: |-
|
|
An array of server names that are likely to hold the given room. This
|
|
list may or may not include the server answering the query.
|
|
items:
|
|
type: string
|
|
required:
|
|
- room_id
|
|
- servers
|
|
examples:
|
|
response:
|
|
value: {
|
|
"room_id": "!roomid1234:example.org",
|
|
"servers": [
|
|
"example.org",
|
|
"example.com",
|
|
"another.example.com:8449"
|
|
]
|
|
}
|
|
"404":
|
|
description: The room alias was not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "Room alias not found."
|
|
}
|
|
/query/profile:
|
|
get:
|
|
summary: Query for profile information about a given user
|
|
description: |-
|
|
Performs a query to get profile information, such as a display name or avatar,
|
|
for a given user. Homeservers should only query profiles for users that belong
|
|
to the target server (identified by the [server name](/appendices/#server-name)
|
|
in the user ID).
|
|
|
|
Servers may wish to cache the response to this query to avoid requesting the
|
|
information too often.
|
|
|
|
Servers MAY deny profile look-up over federation by responding with 403 and an
|
|
error code of `M_FORBIDDEN`.
|
|
operationId: queryProfile
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: query
|
|
name: user_id
|
|
description: The user ID to query. Must be a user local to the receiving homeserver.
|
|
required: true
|
|
example: "@someone:example.org"
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: field
|
|
description: |-
|
|
The field to query. If specified, the server will only return the given field
|
|
in the response. If not specified, the server will return the full profile for
|
|
the user.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- displayname
|
|
- avatar_url
|
|
responses:
|
|
"200":
|
|
description: |-
|
|
The profile for the user. If a `field` is specified in the request, only the
|
|
matching field should be included in the response. If no `field` was specified,
|
|
the response should include the fields of the user's profile that can be made
|
|
public, such as the display name and avatar.
|
|
|
|
If the user does not have a particular field set on their profile, the server
|
|
should exclude it from the response body or give it the value `null`.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
displayname:
|
|
type: string
|
|
description: |-
|
|
The display name of the user. May be omitted if the user does not have a
|
|
display name set.
|
|
example: John Doe
|
|
avatar_url:
|
|
type: string
|
|
description: |-
|
|
The avatar URL for the user's avatar. May be omitted if the user does not
|
|
have an avatar set.
|
|
example: mxc://matrix.org/MyC00lAvatar
|
|
examples:
|
|
response:
|
|
value: {
|
|
"displayname": "John Doe",
|
|
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
|
|
}
|
|
"403":
|
|
x-addedInMatrixVersion: "1.12"
|
|
description: The server is unwilling to disclose whether the user exists and/or
|
|
has profile information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Profile lookup over federation is disabled on this homeserver"
|
|
}
|
|
"404":
|
|
description: The user does not exist or does not have a profile.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "User does not exist."
|
|
}
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8448
|
|
basePath:
|
|
default: /_matrix/federation/v1
|
|
components:
|
|
securitySchemes:
|
|
signedRequest:
|
|
$ref: definitions/security.yaml#/signedRequest
|