Merge pull request #126 from matrix-org/rav/send_events_api
Add the room send and state APIs to the spec
This commit is contained in:
Richard van der Hoff
commit
f47a49de43
3 changed files with 249 additions and 63 deletions
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.
|
||||
80
api/client-server/v1/room_state.yaml
Normal file
80
api/client-server/v1/room_state.yaml
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue