Merge pull request #139 from matrix-org/erikj/event_context_api
Add event context api swagger
This commit is contained in:
Erik Johnston
commit
c4085b0475
4 changed files with 171 additions and 0 deletions
151
api/client-server/event_context.yaml
Normal file
151
api/client-server/event_context.yaml
Normal file
|
|
@ -0,0 +1,151 @@
|
|||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Event Context API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION%
|
||||
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}/context/{eventId}":
|
||||
get:
|
||||
summary: Get events and state around the specified event.
|
||||
description: |-
|
||||
This API returns a number of events that happened just before and
|
||||
after the specified event. This allows clients to get the context
|
||||
surrounding an event.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The room to get events from.
|
||||
required: true
|
||||
x-example: "!636q39766251:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: eventId
|
||||
description: The event to get context around.
|
||||
required: true
|
||||
x-example: "$f3h4d129462ha:example.com"
|
||||
- in: query
|
||||
type: integer
|
||||
name: limit
|
||||
description: |-
|
||||
The maximum number of events to return. Default: 10.
|
||||
x-example: 3
|
||||
responses:
|
||||
200:
|
||||
description: The events and state surrounding the requested event.
|
||||
schema:
|
||||
type: object
|
||||
description: The events and state surrounding the requested event.
|
||||
properties:
|
||||
start:
|
||||
type: string
|
||||
description: |-
|
||||
A token that can be used to paginate backwards with.
|
||||
end:
|
||||
type: string
|
||||
description: |-
|
||||
A token that can be used to paginate forwards with.
|
||||
events_before:
|
||||
type: array
|
||||
description: |-
|
||||
A list of room events that happened just before the
|
||||
requested event.
|
||||
items:
|
||||
type: object
|
||||
title: RoomEvent
|
||||
events_after:
|
||||
type: array
|
||||
description: |-
|
||||
A list of room events that happened just after the
|
||||
requested event.
|
||||
items:
|
||||
type: object
|
||||
title: RoomEvent
|
||||
state:
|
||||
type: array
|
||||
description: |-
|
||||
The state of the room at the last event returned.
|
||||
items:
|
||||
type: object
|
||||
title: RoomEvent
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"end": "t29-57_2_0_2",
|
||||
"events_after": [
|
||||
{
|
||||
"age": 91911336,
|
||||
"content": {
|
||||
"body": "7",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$14460306086CiUaL:localhost:8480",
|
||||
"origin_server_ts": 1446030608551,
|
||||
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
|
||||
"type": "m.room.message",
|
||||
"user_id": "@test:localhost:8480"
|
||||
}
|
||||
],
|
||||
"events_before": [
|
||||
{
|
||||
"age": 91911903,
|
||||
"content": {
|
||||
"body": "5",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$14460306074UYTlh:localhost:8480",
|
||||
"origin_server_ts": 1446030607984,
|
||||
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
|
||||
"type": "m.room.message",
|
||||
"user_id": "@test:localhost:8480"
|
||||
}
|
||||
],
|
||||
"start": "t27-54_2_0_2",
|
||||
"state": [
|
||||
{
|
||||
"age": 3123715284,
|
||||
"content": {
|
||||
"creator": "@test:localhost:8480"
|
||||
},
|
||||
"event_id": "$14429988040dgQAE:localhost:8480",
|
||||
"origin_server_ts": 1442998804603,
|
||||
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
|
||||
"state_key": "",
|
||||
"type": "m.room.create",
|
||||
"user_id": "@test:localhost:8480"
|
||||
},
|
||||
{
|
||||
"age": 2067105053,
|
||||
"content": {
|
||||
"avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
|
||||
"displayname": "Bob2",
|
||||
"membership": "join"
|
||||
},
|
||||
"event_id": "$14440554144URDbf:localhost:8480",
|
||||
"origin_server_ts": 1444055414834,
|
||||
"replaces_state": "$14440552472PgiGk:localhost:8480",
|
||||
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
|
||||
"state_key": "@test:localhost:8480",
|
||||
"type": "m.room.member",
|
||||
"user_id": "@test:localhost:8480"
|
||||
}
|
||||
]
|
||||
}
|
||||
tags:
|
||||
- Room participation
|
||||
|
|
@ -27,6 +27,7 @@ Summary
|
|||
`Managing History Visibility`_ Required Required Required Required Optional
|
||||
`Server Side Search`_ Optional Optional Optional Optional Optional
|
||||
`Server Administration`_ Optional Optional Optional Optional Optional
|
||||
`Event Context`_ Optional Optional Optional Optional Optional
|
||||
===================================== ========== ========== ========== ========== ==========
|
||||
|
||||
*Please see each module for more details on what clients need to implement.*
|
||||
|
|
@ -41,6 +42,7 @@ Summary
|
|||
.. _Managing History Visibility: `module:history-visibility`_
|
||||
.. _Server Side Search: `module:search`_
|
||||
.. _Server Administration: `module:admin`_
|
||||
.. _Event Context: `module:event-context`_
|
||||
|
||||
Clients
|
||||
-------
|
||||
|
|
|
|||
17
specification/modules/event_context.rst
Normal file
17
specification/modules/event_context.rst
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
Event Context
|
||||
=============
|
||||
|
||||
.. _module:event-context:
|
||||
|
||||
This API returns a number of events that happened just before and after the
|
||||
specified event. This allows clients to get the context surrounding an event.
|
||||
|
||||
Client behaviour
|
||||
----------------
|
||||
|
||||
{{event_context_http_api}}
|
||||
|
||||
Security considerations
|
||||
-----------------------
|
||||
|
||||
The server must only return results that the user has permission to see.
|
||||
|
|
@ -36,6 +36,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
|
|||
- modules/tags.rst
|
||||
- modules/account_data.rst
|
||||
- modules/admin.rst
|
||||
- modules/event_context.rst
|
||||
|
||||
|
||||
title_styles: ["=", "-", "~", "+", "^", "`", "@"]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue