# Copyright 2023 Tulir Asokan
#
# 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 Client-Server Application Service Ping API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  # Note: this is the same access_token definition used elsewhere in the client
  # server API, however this expects an access token for an application service.
  $ref: definitions/security.yaml
paths:
  "/appservice/{appserviceId}/ping":
    post:
      x-addedInMatrixVersion: "1.7"
      summary: |-
        Ask the homeserver to ping the application service to ensure the connection works.
      description: |-
        This API asks the homeserver to call the
        [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
        application service to ensure that the homeserver can communicate
        with the application service.

        This API requires the use of an application service access token (`as_token`)
        instead of a typical client's access token. This API cannot be invoked by
        users who are not identified as application services. Additionally, the
        appservice ID in the path must be the same as the appservice whose `as_token`
        is being used.
      operationId: pingAppservice
      parameters:
        - in: path
          type: string
          name: appserviceId
          description: |-
            The appservice ID of the appservice to ping. This must be the same
            as the appservice whose `as_token` is being used to authenticate the
            request.
          required: true
          x-example: "telegram"
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              transaction_id:
                type: string
                description: |-
                  An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call.
                example: "mautrix-go_1683636478256400935_123"
      security:
        # again, this is the appservice's token - not a typical client's
        - accessToken: []
      responses:
        200:
          description: The ping was successful.
          schema:
            type: object
            properties:
              duration_ms:
                type: integer
                description: |-
                    The duration in milliseconds that the
                    [`/_matrix/app/v1/ping`](#post_matrixappv1ping)
                    request took from the homeserver's point of view.
            required:
              - duration_ms
          examples:
            application/json: {"duration_ms": 123}
        400:
          description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_URL_NOT_SET",
              "error": "Application service doesn't have a URL configured"
            }
        403:
          description: The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_FORBIDDEN",
              "error": "Provided access token is not the appservice's as_token"
            }
        502:
          description: |-
            The application service returned a bad status, or the connection failed.
            The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.

            For bad statuses, the response may include `status` and `body`
            fields containing the HTTP status code and response body text
            respectively to aid with debugging.
          schema:
            type: object
            title: Error
            description: A Matrix-level Error
            properties:
              errcode:
                type: string
                description: An error code.
                enum: [M_BAD_STATUS, M_CONNECTION_FAILED]
              error:
                type: string
                description: A human-readable error message.
                example: Ping returned status 401
              status:
                type: integer
                description: The HTTP status code returned by the appservice.
                example: 401
              body:
                type: string
                description: The HTTP response body returned by the appservice.
                example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
            required: ["errcode"]
          examples:
            application/json: {
              "errcode": "M_BAD_STATUS",
              "error": "Ping returned status 401",
              "status": 401,
              "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
            }
        504:
          description: The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`.
          schema:
            $ref: "definitions/errors/error.yaml"
          examples:
            application/json: {
              "errcode": "M_CONNECTION_TIMEOUT",
              "error": "Connection to application service timed out"
            }