Merge pull request #201 from matrix-org/daniel/statekeys

Explicitly document /rooms/{roomId}/state/{eventType} without state key

api/client-server/room_state.yaml

@@ -20,12 +20,12 @@ securityDefinitions:
 paths:
   "/rooms/{roomId}/state/{eventType}/{stateKey}":
     put:
-      summary: Send a message event to the given room.
+      summary: Send a state event to the given room.
       description: |
-        State events can be sent using this endpoint.  These events will be
-        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
-        match.  If the state event has an empty ``state_key``, it can be
-        omitted from the path.
+        State events can be sent using this endpoint. This endpoint is
+        equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
+        with an empty `stateKey`. Previous state events with matching
+        `<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
 
         Requests to this endpoint **cannot use transaction IDs**
         like other ``PUT`` paths because they cannot be differentiated from the
@@ -78,3 +78,56 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+  "/rooms/{roomId}/state/{eventType}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint.  These events will be
+        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+        match. This endpoint forces the state key to be the empty string.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other ``PUT`` paths because they cannot be differentiated from the
+        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        `Room Events`_ for the ``m.`` event specification.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to set the state in
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.name"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                  "name": "New name for the room"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.

api/client-server/rooms.yaml

@@ -44,7 +44,7 @@ paths:
         - in: path
           type: string
           name: stateKey
-          description: The key of the state to look up. Defaults to the empty string.
+          description: The key of the state to look up.
           required: true
           x-example: ""
       responses:
@@ -62,6 +62,47 @@ paths:
             You aren't a member of the room and weren't previously a
             member of the room.
 
+  "/rooms/{roomId}/state/{eventType}":
+    get:
+      summary: Get the state identified by the type, with the empty state key.
+      description: |-
+        Looks up the contents of a state event in a room. If the user is
+        joined to the room then the state is taken from the current
+        state of the room. If the user has left the room then the state is
+        taken from the state of the room when they left.
+
+        This looks up the state event with the empty state key.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to look up the state in.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of state to look up.
+          required: true
+          x-example: "m.room.name"
+      responses:
+        200:
+          description: The content of the state event.
+          examples:
+            application/json: |-
+              {"name": "Example room name"}
+          schema:
+            type: object
+        404:
+          description: The room has no state with the given type or key.
+        403:
+          description: >
+            You aren't a member of the room and weren't previously a
+            member of the room.
+
+
   "/rooms/{roomId}/state":
     get:
       summary: Get all state events in the current state of a room.