matrix-spec-proposals/api/server-server/query.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.

swagger: '2.0'
info:
  title: "Matrix Federation Query API"
  version: "1.0.0"
host: localhost:8448
schemes:
  - https
basePath: /_matrix/federation/v1
produces:
  - application/json
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
      parameters:
        - in: path
          name: queryType
          type: string
          description: The type of query to make
          required: true
          x-example: profile
      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 (idenfified by the DNS Name in the alias).
        The target server may not appear in the resident servers list.

        Servers may wish to cache the response to this query to prevent requesting the
        information too often.
      operationId: queryRoomDirectory
      parameters:
        - in: query
          name: room_alias
          type: string
          description: The room alias to query.
          required: true
          x-example: "#room_alias:example.org"
      responses:
        200:
          description: |-
            The corresponding room ID and list of known resident homeservers for the room.
          schema:
            type: object
            properties:
              room_id:
                type: string
                description: The room ID mapped to the queried room alias.
                x-example: "!roomid1234:example.org"
              servers:
                type: array
                description: |-
                  An array of server names that are likely to hold then given room. This 
                  list may or may not include the server answering the query.
                items:
                  type: string
            required:
              - "room_id"
              - "servers"
          examples:
            application/json: {
              "room_id": "!roomid1234:example.org",
              "servers": [
                "example.org",
                "example.com",
                "another.example.com:8449",
              ]
            }
        400:
          description: |-
            The room alias is not hosted on the server. This can happen if the directory
            server is named "example.org" and the room alias ends with "matrix.org".
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_UNKNOWN",
              "error": "Room alias not hosted on this homeserver."
            }
        404:
          description: The room alias was not found.
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "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 DNS Name in the user ID).

        Servers may wish to cache the response to this query to prevent requesting the
        information too often.
      parameters:
        - in: query
          name: user_id
          type: string
          description: The user ID to query.
          required: true
          x-example: "@someone:example.org"
        - in: query
          name: field
          type: string
          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.
      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 ``field`` is for a field that the server does not recognize, an empty object
            should be returned. If the ``field`` is recognized, but the user does not have it
            set on their profile, ``null`` should be returned for the value of that field.

            If the user does not exist, an empty object should be returned regardless of the
            ``field`` being queried.
          schema:
            type: object
            properties:
              displayname:
                type: string
                description: |-
                  The display name of the user. If the user does not have a display name set,
                  this should be the value ``null``.
                x-example: "John Doe"
              avatar_url:
                type: string
                description: |-
                  The avatar URL for the user's avatar. If the user does not have an avatar
                  set, this should be the value ``null``.
                x-example: "mxc://matrix.org/MyC00lAvatar"
          examples:
            application/json: {
              "displayname": "John Doe",
              "avatar_url": "mxc://matrix.org/MyC00lAvatar"
            }
        400:
          description: The user does not belong to the server.
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_UNKNOWN",
              "error": "User is not hosted on this homeserver."
            }