From d18d406c41e0658b376555d666dc3690749fab5e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 23 Oct 2015 12:49:17 +0100 Subject: [PATCH 1/3] Add the room send and state APIs to the spec --- api/client-server/v1/room_send.yaml | 125 +++++++++++++++++++++++++++ api/client-server/v1/room_state.yaml | 78 +++++++++++++++++ specification/client_server_api.rst | 64 +++++--------- 3 files changed, 227 insertions(+), 40 deletions(-) create mode 100644 api/client-server/v1/room_send.yaml create mode 100644 api/client-server/v1/room_state.yaml diff --git a/api/client-server/v1/room_send.yaml b/api/client-server/v1/room_send.yaml new file mode 100644 index 00000000..9c9273df --- /dev/null +++ b/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. diff --git a/api/client-server/v1/room_state.yaml b/api/client-server/v1/room_state.yaml new file mode 100644 index 00000000..0c0e76e6 --- /dev/null +++ b/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 ````, ```` and ```` 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. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 791c1f4a..4df821e0 100644 --- a/specification/client_server_api.rst +++ b/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 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are several APIs provided to ``GET`` events for a room: + +{{rooms_http_api}} + + +{{message_pagination_http_api}} + + +Sending events to a room +~~~~~~~~~~~~~~~~~~~~~~~~ + +{{room_state_http_api}} + + +**Examples** -State events can be sent by ``PUT`` ing to -|/rooms//state//|_. These events will be -overwritten if ````, ```` and ```` 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:: +Valid requests look like:: - PUT /rooms/!roomid:domain/state/m.example.event - { "key" : "without a state key" } + 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" } + 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//send/|_. 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 ~~~~~~~~~~ From d2bbc461e4b2bb473c4a190aacbf4ecf4796da4b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 23 Oct 2015 13:25:12 +0100 Subject: [PATCH 2/3] mark stateKey as required in room/{id}/state Swagger insists that path params be mandatory. --- api/client-server/v1/room_state.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/v1/room_state.yaml b/api/client-server/v1/room_state.yaml index 0c0e76e6..bd8e2946 100644 --- a/api/client-server/v1/room_state.yaml +++ b/api/client-server/v1/room_state.yaml @@ -51,15 +51,15 @@ paths: type: string name: stateKey description: The state_key for the state to send. Defaults to the empty string. - required: false + required: true x-example: "" - in: body name: body schema: type: object - example: | + example: |- { - "name": "The room name" + "name": "New name for the room" } responses: 200: From 19456974567dbb52189ea247406c71fd64f111b2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 23 Oct 2015 16:58:55 +0100 Subject: [PATCH 3/3] Further tweaks to the room send and state APIs - fix confusion re empty/absent state_keys - move 'types of room events' section earlier in the 'Events' section - remove some redundant anchors --- api/client-server/v1/room_state.yaml | 8 +++-- specification/client_server_api.rst | 51 +++++++++++++--------------- 2 files changed, 29 insertions(+), 30 deletions(-) diff --git a/api/client-server/v1/room_state.yaml b/api/client-server/v1/room_state.yaml index bd8e2946..ec30fd34 100644 --- a/api/client-server/v1/room_state.yaml +++ b/api/client-server/v1/room_state.yaml @@ -24,9 +24,11 @@ paths: description: | State events can be sent using this endpoint. These events will be overwritten if ````, ```` and ```` 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 + match. If the state event has an empty ``state_key``, it can be + omitted from the path. + + 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 diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 4df821e0..9e89ecf4 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -647,6 +647,30 @@ To continue paginating backwards, one calls the /messages API again, supplying the new ``start`` value as the ``from`` parameter. +Types of room events +~~~~~~~~~~~~~~~~~~~~ + +Room events are split into two categories: + +:State Events: + These are events which update the metadata state of the room (e.g. room topic, + room membership etc). State is keyed by a tuple of event ``type`` and a + ``state_key``. State in the room with the same key-tuple will be overwritten. + +:Message events: + These are events which describe transient "once-off" activity in a room: + typically communication such as sending an instant message or setting up a + VoIP call. + +This specification outlines several events, all with the event type prefix +``m.``. (See `Room Events`_ for the m. event specification.) However, +applications may wish to add their own type of event, and this can be achieved +using the REST API detailed in the following sections. If new 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. + + Syncing ~~~~~~~ @@ -675,27 +699,6 @@ This API also returns an ``end`` token which can be used with the event stream. {{sync_http_api}} -Types of room events -~~~~~~~~~~~~~~~~~~~~ - -Room events are split into two categories: - -:State Events: - These are events which update the metadata state of the room (e.g. room topic, - room membership etc). State is keyed by a tuple of event ``type`` and a - ``state_key``. State in the room with the same key-tuple will be overwritten. - -:Message events: - These are events which describe transient "once-off" activity in a room: - typically communication such as sending an instant message or setting up a - VoIP call. - -This specification outlines several events, all with the event type prefix -``m.``. However, applications may wish to add their own type of event, and this -can be achieved using the REST API detailed in the following sections. If new -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. Getting events for a room ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1144,12 +1147,6 @@ have to wait in milliseconds before they can try again. .. |/rooms//state| replace:: ``/rooms//state`` .. _/rooms//state: /docs/api/client-server/#!/-rooms/get_state_events -.. |/rooms//send/| replace:: ``/rooms//send/`` -.. _/rooms//send/: /docs/api/client-server/#!/-rooms/send_non_state_event - -.. |/rooms//state//| replace:: ``/rooms//state//`` -.. _/rooms//state//: /docs/api/client-server/#!/-rooms/send_state_event - .. |/rooms//invite| replace:: ``/rooms//invite`` .. _/rooms//invite: /docs/api/client-server/#!/-rooms/invite