wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #126 from matrix-org/rav/send_events_api

Browse source 
Add the room send and state APIs to the spec
This commit is contained in:
Richard van der Hoff 2015-10-23 17:05:30 +01:00
commit f47a49de43
3 changed files with 249 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

125
api/client-server/v1/room_send.yaml Normal file
View file

@ -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.

80
api/client-server/v1/room_state.yaml Normal file
View file

@ -0,0 +1,80 @@
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 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
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: true
x-example: ""
- 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.

99
specification/client_server_api.rst
View file

@ -595,6 +595,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
~~~~~~~
@ -623,38 +647,27 @@ 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:
Getting events for a room
~~~~~~~~~~~~~~~~~~~~~~~~~
: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.
There are several APIs provided to ``GET`` events for a room:
: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.
{{rooms_http_api}}
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.
State events
++++++++++++
{{message_pagination_http_api}}
State events can be sent by ``PUT`` ing to
|/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::
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" }
@ -686,34 +699,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
~~~~~~~~~~
@ -1007,12 +994,6 @@ have to wait in milliseconds before they can try again.
.. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state``
.. _/rooms/<room_id>/state: /docs/api/client-server/#!/-rooms/get_state_events
.. |/rooms/<room_id>/send/<event_type>| replace:: ``/rooms/<room_id>/send/<event_type>``
.. _/rooms/<room_id>/send/<event_type>: /docs/api/client-server/#!/-rooms/send_non_state_event
.. |/rooms/<room_id>/state/<event_type>/<state_key>| replace:: ``/rooms/<room_id>/state/<event_type>/<state_key>``
.. _/rooms/<room_id>/state/<event_type>/<state_key>: /docs/api/client-server/#!/-rooms/send_state_event
.. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite``
.. _/rooms/<room_id>/invite: /docs/api/client-server/#!/-rooms/invite