From fa2fe2ddd9e290ff8e339be6666f496c8ba06e7c Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Oct 2015 12:43:36 +0000 Subject: [PATCH 1/8] Add event context api swagger --- api/client-server/v1/event_context.yaml | 152 ++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 api/client-server/v1/event_context.yaml diff --git a/api/client-server/v1/event_context.yaml b/api/client-server/v1/event_context.yaml new file mode 100644 index 00000000..808055eb --- /dev/null +++ b/api/client-server/v1/event_context.yaml @@ -0,0 +1,152 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v1 Rooms 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}/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 of + 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: "!636q39766251: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" + } + ] + } + 403: + description: > + You aren't a member of the room. From 584104c432aca36fa405888b40e662a449a7a03c Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 16:32:43 +0000 Subject: [PATCH 2/8] Make example valid event id --- api/client-server/event_context.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 808055eb..c0fbd0b8 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -39,7 +39,7 @@ paths: name: eventId description: The event to get context around. required: true - x-example: "!636q39766251:example.com" + x-example: "$f3h4d129462ha:example.com" - in: query type: integer name: limit From f4b9433c7b28a38f035a31765066b200586d8050 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 16:33:48 +0000 Subject: [PATCH 3/8] Better wording --- api/client-server/event_context.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index c0fbd0b8..71fa9c44 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -23,8 +23,8 @@ paths: 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 of - an event. + after the specified event. This allows clients to get the context + surrounding an event. security: - accessToken: [] parameters: From dd276d4c4dd75e64ca90ac5ddc03ca92faae5db2 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 16:56:03 +0000 Subject: [PATCH 4/8] Add event context module --- specification/feature_profiles.rst | 2 ++ specification/modules/event_context.rst | 17 +++++++++++++++++ specification/targets.yaml | 1 + 3 files changed, 20 insertions(+) create mode 100644 specification/modules/event_context.rst 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: ["=", "-", "~", "+", "^", "`", "@"] From 8e7f6d44f6eca6a258d4b4eeb46168cda1911b01 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 14:01:16 +0000 Subject: [PATCH 5/8] Remove v1 references --- api/client-server/event_context.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 71fa9c44..2418f672 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -1,12 +1,12 @@ swagger: '2.0' info: - title: "Matrix Client-Server v1 Rooms API" + title: "Matrix Client-Server Event Context API" version: "1.0.0" host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/api/v1 +basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: From 4290882034de789c067c6099fbe80d20ddd4a6d0 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 14:06:59 +0000 Subject: [PATCH 6/8] Remove superfluous quote --- api/client-server/event_context.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 2418f672..642643cd 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -45,7 +45,7 @@ paths: name: limit description: |- The maximum number of events to return. Default: 10. - x-example: "3" + x-example: 3 responses: 200: description: The events and state surrounding the requested event. From 0fb88e26f01a9a49c138995a98a9e9d195fdf972 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 14:07:08 +0000 Subject: [PATCH 7/8] Add tags --- api/client-server/event_context.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 642643cd..1a99fd10 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -150,3 +150,5 @@ paths: 403: description: > You aren't a member of the room. + tags: + - Room participation From 6025569a739da060d651ccc2721d191dd0a57b3f Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 14:10:45 +0000 Subject: [PATCH 8/8] Remove unused 403 stub --- api/client-server/event_context.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 1a99fd10..da2be90f 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -147,8 +147,5 @@ paths: } ] } - 403: - description: > - You aren't a member of the room. tags: - Room participation