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.
151 lines
5.8 KiB
YAML
151 lines
5.8 KiB
YAML
# 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.
|
|
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"
|
|
}
|