Add the room send and state APIs to the spec

api/client-server/v1/room_send.yaml

@@ -0,0 +1,125 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 message event send API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/send/{eventType}/{txnId}":
+    put:
+      summary: Send a message event to the given room.
+      description: |-
+        This endpoint is used to send a message event to a room. Message events
+        allow access to historical events and pagination, making them suited
+        for "once-off" activity in a room.
+
+        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 send the event to.
+          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.message"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate a
+            unique ID; it will be used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "msgtype": "m.text",
+                "body": "hello"
+              }
+      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.
+  "/rooms/{roomId}/send/{eventType}":
+    post:
+      summary: Send a message event to the given room.
+      description: |-
+        This endpoint can be used to send a message event to a room; however
+        the lack of a transaction ID means that it is possible to cause message
+        duplication if events are resent on error, so it is preferable to use
+        `PUT /_matrix/client/api/v1/rooms/{roomId}/send/{eventType}/{txnId}`_.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to send the event to.
+          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.message"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "msgtype": "m.text",
+                "body": "hello"
+              }
+      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/v1/room_state.yaml

@@ -0,0 +1,78 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 state event send API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/state/{eventType}/{stateKey}":
+    put:
+      summary: Send a message 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 no ``state_key``, it can be omitted from
+        the path. These requests **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: path
+          type: string
+          name: stateKey
+          description: The state_key for the state to send. Defaults to the empty string.
+          required: false
+          x-example: ""
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |
+              {
+                  "name": "The room name"
+              }
+      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.

specification/client_server_api.rst

@@ -697,22 +697,32 @@ events are added, the event ``type`` key SHOULD follow the Java package naming
 convention, e.g. ``com.example.myapp.event``.  This ensures event types are
 suitably namespaced for each application and reduces the risk of clashes.
 
-State events
+Getting events for a room
-++++++++++++
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-State events can be sent by ``PUT`` ing to
+There are several APIs provided to ``GET`` events for a room:
-|/rooms/<room_id>/state/<event_type>/<state_key>|_.  These events will be
-overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all match.
-If the state event has no ``state_key``, it can be omitted from the path. These
-requests **cannot use transaction IDs** like other ``PUT`` paths because they
-cannot be differentiated from the ``state_key``. Furthermore, ``POST`` is
-unsupported on state paths. Valid requests look like::
 
-  PUT /rooms/!roomid:domain/state/m.example.event
+{{rooms_http_api}}
-  { "key" : "without a state key" }
 
-  PUT /rooms/!roomid:domain/state/m.another.example.event/foo
+
-  { "key" : "with 'foo' as the state key" }
+{{message_pagination_http_api}}
+
+
+Sending events to a room
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+{{room_state_http_api}}
+
+
+**Examples**
+
+Valid requests look like::
+
+    PUT /rooms/!roomid:domain/state/m.example.event
+    { "key" : "without a state key" }
+
+    PUT /rooms/!roomid:domain/state/m.another.example.event/foo
+    { "key" : "with 'foo' as the state key" }
 
 In contrast, these requests are invalid::
 
@@ -738,34 +748,8 @@ In some cases, there may be no need for a ``state_key``, so it can be omitted::
   PUT /rooms/!roomid:domain/state/m.room.bgd.color
   { "color": "red", "hex": "#ff0000" }
 
-See `Room Events`_ for the ``m.`` event specification.
+{{room_send_http_api}}
 
-Message events
-++++++++++++++
-
-Message events can be sent by sending a request to
-|/rooms/<room_id>/send/<event_type>|_.  These requests *can* use transaction
-IDs and ``PUT``/``POST`` methods. Message events allow access to historical
-events and pagination, making it best suited for sending messages.  For
-example::
-
-  POST /rooms/!roomid:domain/send/m.custom.example.message
-  { "text": "Hello world!" }
-
-  PUT /rooms/!roomid:domain/send/m.custom.example.message/11
-  { "text": "Goodbye world!" }
-
-See `Room Events`_ for the ``m.`` event specification.
-
-Getting events for a room
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are several APIs provided to ``GET`` events for a room:
-
-{{rooms_http_api}}
-
-
-{{message_pagination_http_api}}
 
 Redactions
 ~~~~~~~~~~