From fa2fe2ddd9e290ff8e339be6666f496c8ba06e7c Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Thu, 29 Oct 2015 12:43:36 +0000
Subject: [PATCH] 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 000000000..808055eb3
--- /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.