Merge pull request #139 from matrix-org/erikj/event_context_api

Add event context api swagger

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

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
 -------

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.

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: ["=", "-", "~", "+", "^", "`", "@"]