From 5cbfa73fe40fa0996f2034f1715f3e63377b9d21 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Tue, 6 Mar 2018 08:51:57 -0700
Subject: [PATCH] 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 <travpc@gmail.com>
---
 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":