From 595667d15dbbe9c1e8580ea62e8095be3f0dbb2f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 3 Mar 2018 14:46:40 -0700 Subject: [PATCH 1/5] Spec /directory/list Adds https://github.com/matrix-org/matrix-doc/issues/417 Signed-off-by: Travis Ralston --- api/client-server/list_public_rooms.yaml | 111 ++++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 6d25a1ac..4d3923bd 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Room Creation API" + title: "Matrix Client-Server Room Directory API" version: "1.0.0" host: localhost:8008 schemes: @@ -25,6 +25,115 @@ consumes: produces: - application/json paths: + "/directory/list/room/{roomId}": + get: + summary: Gets the visibility of a room in the directory + description: |- + Gets the visibility of a given room on the server's public room directory. + operationId: getRoomVisibilityOnDirectory + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + responses: + 200: + description: The visibility of the room in the directory + schema: + type: object + properties: + visibility: + type: string + enum: ['private', 'public'] + description: The visibility of the room in the directory. + examples: + application/json: { + "visibility": "public" + } + 400: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Room not found" + } + put: + summary: Sets the visibility of a room in the room directory + description: |- + Sets the visibility of a given room in the server's public room + directory. + operationId: setRoomVisibilityOnDirectory + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + - in: body + name: body + required: true + description: |- + The new visibility for the room on the room directory. + schema: + type: object + properties: + visibility: + type: string + enum: ["private", "public"] + description: |- + The new visibility setting for the room. + Defaults to 'public'. + example: { + "visibility": "public" + } + responses: + 200: + description: The visibility was updated, or no change was needed. + examples: + application/json: { + } + 400: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Room not found" + } + delete: + summary: Sets a room to be private on the room directory + description: |- + Updates the visibility of a room to be private on the server's room + directory. + operationId: setRoomPrivateOnDirectory + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID. + required: true + x-example: "!curbf:matrix.org" + responses: + 200: + description: The visibility was updated, or no change was needed. + examples: + application/json: { + } + 400: + description: The room is not known to the server + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Room not found" + } "/publicRooms": get: summary: Lists the public rooms on the server. From b41bd9635db85c38966195ecd52f927fc5f1cdb9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 3 Mar 2018 14:50:19 -0700 Subject: [PATCH 2/5] Add /directory/list to changelog Signed-off-by: Travis Ralston --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index d86aeb63..70bc2bd2 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -19,6 +19,8 @@ Unreleased changes (`#1106 `_). - Clarify default values for some fields on the /search API (`#1109 `_). + - Add the room visibility options for the room directory + (`#1141 Date: Tue, 6 Mar 2018 08:50:23 -0700 Subject: [PATCH 3/5] Move /directory/list changelog entry Signed-off-by: Travis Ralston --- changelogs/client_server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index d5c7d048..80927b54 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -23,13 +23,13 @@ Unreleased changes (`#1137 `_). - Clarify that ``m.tag`` ordering is done with numbers, not strings (`#1139 `_). - - Add the room visibility options for the room directory - (`#1141 `_). + - Add the room visibility options for the room directory + (`#1141 `_). r0.3.0 ====== From 5cbfa73fe40fa0996f2034f1715f3e63377b9d21 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 08:51:57 -0700 Subject: [PATCH 4/5] Improve documentation of /directory/list * 404 for room not found instead of 400 * GET doesn't require an access token * PUT (and therefore DELETE) can have it's own access control checks * DELETE is implemented because of synapse Signed-off-by: Travis Ralston --- api/client-server/list_public_rooms.yaml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index 4d3923bd..e6d2616c 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -31,8 +31,6 @@ paths: description: |- Gets the visibility of a given room on the server's public room directory. operationId: getRoomVisibilityOnDirectory - security: - - accessToken: [] parameters: - in: path type: string @@ -54,11 +52,11 @@ paths: application/json: { "visibility": "public" } - 400: + 404: description: The room is not known to the server examples: application/json: { - "errcode": "M_UNKNOWN", + "errcode": "M_NOT_FOUND", "error": "Room not found" } put: @@ -66,6 +64,10 @@ paths: description: |- Sets the visibility of a given room in the server's public room directory. + + Servers may choose to implement additional access control checks + here, for instance that room visibility can only be changed by + the room creator or a server administrator. operationId: setRoomVisibilityOnDirectory security: - accessToken: [] @@ -99,18 +101,19 @@ paths: examples: application/json: { } - 400: + 404: description: The room is not known to the server examples: application/json: { - "errcode": "M_UNKNOWN", + "errcode": "M_NOT_FOUND", "error": "Room not found" } delete: summary: Sets a room to be private on the room directory description: |- Updates the visibility of a room to be private on the server's room - directory. + directory. This is the same as using the PUT operation with a private + as the visibility. operationId: setRoomPrivateOnDirectory security: - accessToken: [] @@ -127,11 +130,11 @@ paths: examples: application/json: { } - 400: + 404: description: The room is not known to the server examples: application/json: { - "errcode": "M_UNKNOWN", + "errcode": "M_NOT_FOUND", "error": "Room not found" } "/publicRooms": From d88a1308c2e9a6075346b91fd79d714bde30f0a5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 10:05:32 -0700 Subject: [PATCH 5/5] Formatting and remove DELETE /directory/list Signed-off-by: Travis Ralston --- api/client-server/list_public_rooms.yaml | 52 +++++------------------- 1 file changed, 11 insertions(+), 41 deletions(-) diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index e6d2616c..334d528c 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/api/client-server/list_public_rooms.yaml @@ -50,15 +50,15 @@ paths: description: The visibility of the room in the directory. examples: application/json: { - "visibility": "public" - } + "visibility": "public" + } 404: description: The room is not known to the server examples: application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } put: summary: Sets the visibility of a room in the room directory description: |- @@ -93,50 +93,20 @@ paths: The new visibility setting for the room. Defaults to 'public'. example: { - "visibility": "public" - } + "visibility": "public" + } responses: 200: description: The visibility was updated, or no change was needed. examples: - application/json: { - } + application/json: {} 404: description: The room is not known to the server examples: application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } - delete: - summary: Sets a room to be private on the room directory - description: |- - Updates the visibility of a room to be private on the server's room - directory. This is the same as using the PUT operation with a private - as the visibility. - operationId: setRoomPrivateOnDirectory - security: - - accessToken: [] - parameters: - - in: path - type: string - name: roomId - description: The room ID. - required: true - x-example: "!curbf:matrix.org" - responses: - 200: - description: The visibility was updated, or no change was needed. - examples: - application/json: { - } - 404: - description: The room is not known to the server - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } "/publicRooms": get: summary: Lists the public rooms on the server.