From bb50ec2e88be7bf95297872173d91702c3becdfe Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Wed, 15 Nov 2017 13:40:55 +0100 Subject: [PATCH 1/5] Document directory query endpoint --- api/server-server/directory.yaml | 67 +++++++++++++++++++++++++++++ specification/server_server_api.rst | 16 +------ 2 files changed, 68 insertions(+), 15 deletions(-) create mode 100644 api/server-server/directory.yaml diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml new file mode 100644 index 00000000..58449fa2 --- /dev/null +++ b/api/server-server/directory.yaml @@ -0,0 +1,67 @@ +# Copyright 2017 Kamax.io +# +# 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 Version API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1/query +produces: + - application/json +paths: + "/directory": + get: + summary: Retrieve the room ID and list of resident homeservers for a room + alias. + description: Retrieve the room ID and list of resident homeservers for a Room + alias. + parameters: + - in: query + name: room_alias + type: string + description: Room alias + 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. + required: true + 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. + required: true + items: + type: string + examples: + application/json: { + "room_id": "!roomid1234:example.org", + "servers": [ + "example.org", + "example.com", + "another.example.com:8449", + ] + } \ No newline at end of file diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 8ffe4e6a..1ca2f39b 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1271,21 +1271,7 @@ Directory The server API for directory queries is also based on Federation Queries. -Querying directory information:: - - Query type: directory - - Arguments: - room_alias: the room alias to query - - Returns: JSON object containing the following keys: - room_id: string giving the underlying room ID the alias maps to - servers: list of strings giving the join candidates - -The list of join candidates is a list of server names that are likely to hold -the given room; these are servers that the requesting server may wish to use as -resident servers as part of the remote join handshake. This list may or may not -include the server answering the query. +{{directory_ss_http_api}} Send-to-device messaging ------------------------ From 8a6103798e61fb542207933a896fd41c3e17f2cf Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Wed, 15 Nov 2017 13:54:55 +0100 Subject: [PATCH 2/5] Fix for tests --- api/server-server/directory.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml index 58449fa2..355970fb 100644 --- a/api/server-server/directory.yaml +++ b/api/server-server/directory.yaml @@ -46,14 +46,12 @@ paths: room_id: type: string description: The room ID mapped to the queried room alias. - required: true 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. - required: true items: type: string examples: From 28c09aed6243c9b1ee6a932400e820c05fcf27f2 Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Wed, 15 Nov 2017 13:57:52 +0100 Subject: [PATCH 3/5] Properly mark required response keys to pass tests --- api/server-server/directory.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml index 355970fb..1321cc4e 100644 --- a/api/server-server/directory.yaml +++ b/api/server-server/directory.yaml @@ -54,6 +54,9 @@ paths: answering the query. items: type: string + required: + - "room_id" + - "servers" examples: application/json: { "room_id": "!roomid1234:example.org", From d1e64daa10c0c16c36263c14a628cb3e98dea78a Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Wed, 15 Nov 2017 18:43:16 +0100 Subject: [PATCH 4/5] Fix yaml title for directory api --- api/server-server/directory.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml index 1321cc4e..3d864ee0 100644 --- a/api/server-server/directory.yaml +++ b/api/server-server/directory.yaml @@ -14,7 +14,7 @@ swagger: '2.0' info: - title: "Matrix Federation Version API" + title: "Matrix Federation Query Directory API" version: "1.0.0" host: localhost:8448 schemes: From 9d2e18cca17ee851e9ea0d9dbc9519ddb2152aeb Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Wed, 15 Nov 2017 18:46:27 +0100 Subject: [PATCH 5/5] Adapt paths as per feedback --- api/server-server/directory.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml index 3d864ee0..c4a06231 100644 --- a/api/server-server/directory.yaml +++ b/api/server-server/directory.yaml @@ -19,11 +19,11 @@ info: host: localhost:8448 schemes: - https -basePath: /_matrix/federation/v1/query +basePath: /_matrix/federation/v1 produces: - application/json paths: - "/directory": + "/query/directory": get: summary: Retrieve the room ID and list of resident homeservers for a room alias.