mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-01 09:14:10 +01:00
Add the room send and state APIs to the spec
This commit is contained in:
Richard van der Hoff
parent
73142fe76e
commit
d18d406c41
125
api/client-server/v1/room_send.yaml
Normal file
125
api/client-server/v1/room_send.yaml
Normal 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.
|
||||
78
api/client-server/v1/room_state.yaml
Normal file
78
api/client-server/v1/room_state.yaml
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|/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::
|
||||
There are several APIs provided to ``GET`` events for a room:
|
||||
|
||||
PUT /rooms/!roomid:domain/state/m.example.event
|
||||
{ "key" : "without a state key" }
|
||||
{{rooms_http_api}}
|
||||
|
||||
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
|
||||
~~~~~~~~~~
|
||||
|
|
|
|||
Loading…
Reference in a new issue