Merge pull request #1518 from turt2live/travis/c2s/create-room-improvements

Add general clarity to the /createRoom endpoint

api/client-server/create_room.yaml

@@ -39,16 +39,20 @@ paths:
         apply the events implied by the request in the following order:
 
         0. A default ``m.room.power_levels`` event, giving the room creator
-           (and not other members) permission to send state events.
+           (and not other members) permission to send state events. Overridden
+           by the ``power_level_content_override`` parameter.
         
-        1. Events set by the ``preset``.
+        1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
+           ``m.room.history_visibility``, and ``m.room.guest_access`` state events.
 
         2. Events listed in ``initial_state``, in the order that they are
            listed.
 
-        3. Events implied by ``name`` and ``topic``.
+        3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
+           state events).
 
-        4. Invite events implied by ``invite`` and ``invite_3pid``.
+        4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
+           ``membership: invite`` and ``m.room.third_party_invite``).
 
         The available presets do the following with respect to room state:
 
@@ -60,6 +64,9 @@ paths:
         ``public_chat``           ``public``      ``shared``              ``forbidden``     
         ========================  ==============  ======================  ================  =========
 
+        The server will create a ``m.room.create`` event in the room with the
+        requesting user as the creator, alongside other keys provided in the 
+        ``creation_content``.
       operationId: createRoom
       security:
         - accessToken: []
@@ -70,14 +77,14 @@ paths:
           schema:
             type: object
             example: {
-                "preset": "public_chat",
-                "room_alias_name": "thepub",
-                "name": "The Grand Duke Pub",
-                "topic": "All about happy hour",
-                "creation_content": {
-                    "m.federate": false
-                }
+              "preset": "public_chat",
+              "room_alias_name": "thepub",
+              "name": "The Grand Duke Pub",
+              "topic": "All about happy hour",
+              "creation_content": {
+                  "m.federate": false
               }
+            }
             properties:
               visibility:
                 type: string
@@ -98,6 +105,9 @@ paths:
                   created the room. For example, if this was set to "foo" and
                   sent to the homeserver "example.com" the complete room alias
                   would be ``#foo:example.com``.
+
+                  The complete room alias will become the canonical alias for
+                  the room.
               name:
                 type: string
                 description: |-
@@ -141,10 +151,10 @@ paths:
                 title: CreationContent
                 type: object
                 description: |-
-                  Extra keys to be added to the content of the ``m.room.create``.
-                  The server will clobber the following keys: ``creator``. Future
-                  versions of the specification may allow the server to clobber
-                  other keys.
+                  Extra keys, such as ``m.federate``, to be added to the content
+                  of the `m.room.create`_ event. The server will clobber the following
+                  keys: ``creator``. Future versions of the specification may allow
+                  the server to clobber other keys.
               initial_state:
                 type: array
                 description: |-
@@ -175,16 +185,25 @@ paths:
                 description: |-
                   Convenience parameter for setting various default state events
                   based on a preset.
+
+                  If unspecified, the server should use the ``visibility`` to determine
+                  which preset to use. A visbility of ``public`` equates to a preset of
+                  ``public_chat`` and ``private`` visibility equates to a preset of 
+                  ``private_chat``.
               is_direct:
                 type: boolean
                 description: |-
                   This flag makes the server set the ``is_direct`` flag on the
                   ``m.room.member`` events sent to the users in ``invite`` and
                   ``invite_3pid``. See `Direct Messaging`_ for more information.
-              guest_can_join:
-                type: boolean
+              power_level_content_override:
+                title: Power Level Event Content
+                type: object
                 description: |-
-                  Allows guests to join the room. See `Guest Access`_ for more information.
+                  The power level content to override in the default power level
+                  event. This object is applied on top of the generated `m.room.power_levels`_
+                  event content prior to it being sent to the room. Defaults to
+                  overriding nothing.
       responses:
         200:
           description: Information about the newly created room.
@@ -196,10 +215,11 @@ paths:
                 type: string
                 description: |-
                   The created room's ID.
+            required: ['room_id']
           examples:
             application/json: {
-                "room_id": "!sefiuhWgwghwWgh:example.com"
-              }
+              "room_id": "!sefiuhWgwghwWgh:example.com"
+            }
         400:
           description: |-
 
@@ -218,6 +238,5 @@ paths:
               ``M_INVALID_ROOM_STATE``).
           schema:
             "$ref": "definitions/errors/error.yaml"
-
       tags:
         - Room creation

changelogs/client_server/newsfragments/1518.clarification

@@ -0,0 +1 @@
+Document additional parameters on the ``/createRoom`` API.