diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml new file mode 100644 index 00000000..da2be90f --- /dev/null +++ b/api/client-server/event_context.yaml @@ -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 diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index a5d19a61..bb1ee2ad 100644 --- a/specification/feature_profiles.rst +++ b/specification/feature_profiles.rst @@ -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 ------- diff --git a/specification/modules/event_context.rst b/specification/modules/event_context.rst new file mode 100644 index 00000000..2f798caa --- /dev/null +++ b/specification/modules/event_context.rst @@ -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. diff --git a/specification/targets.yaml b/specification/targets.yaml index cbe40dc7..ca3aa215 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -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: ["=", "-", "~", "+", "^", "`", "@"]