From e02c69de83ff235b81f4b6c27596aba18b4a4e39 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 23 May 2023 11:48:37 +0300 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- data/api/application-service/ping.yaml | 2 +- data/api/client-server/appservice_ping.yaml | 14 ++++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml index 1de4094f..c4f12b4f 100644 --- a/data/api/application-service/ping.yaml +++ b/data/api/application-service/ping.yaml @@ -56,7 +56,7 @@ paths: client API appservice ping call. responses: 200: - description: The hs_token is valid and the ping request was successful. + description: The provided `hs_token` is valid and the ping request was successful. examples: application/json: {} schema: diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml index c5e54f13..4075e901 100644 --- a/data/api/client-server/appservice_ping.yaml +++ b/data/api/client-server/appservice_ping.yaml @@ -35,12 +35,13 @@ paths: 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` endpoint - on the application service to ensure that the homeserver can communicate + 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 + 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. @@ -71,15 +72,16 @@ paths: - accessToken: [] responses: 200: - description: The ping was successful + description: The ping was successful. schema: type: object properties: duration_ms: type: integer description: |- - The duration that the `/_matrix/app/v1/ping` request took - from the homeserver's point of view. + 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: