From c16ba9488f28c44f0c0d13b10a9bd8d76a1bf36e Mon Sep 17 00:00:00 2001
From: David Baker <dave@matrix.org>
Date: Wed, 5 Oct 2016 10:15:49 +0100
Subject: [PATCH] Spec notifs API

---
 api/client-server/notifications.yaml | 126 +++++++++++++++++++++++++++
 specification/modules/push.rst       |   9 ++
 2 files changed, 135 insertions(+)
 create mode 100644 api/client-server/notifications.yaml

diff --git a/api/client-server/notifications.yaml b/api/client-server/notifications.yaml
new file mode 100644
index 00000000..32fd12a1
--- /dev/null
+++ b/api/client-server/notifications.yaml
@@ -0,0 +1,126 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Notifications API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/notifications":
+    get:
+      summary: Gets a list of events that the user has been notified about
+      description: |-
+        This API is used to paginate through the list of events that the
+        user has been, or would have been notified about.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: from
+          description: Pagination token given to retrieve the next set of events.
+          required: false
+          x-example: "xxxxx"
+        - in: path
+          type: number
+          name: limit
+          description: Limit on the number of events to return in this request.
+          required: false
+          x-example: "20"
+        - in: path
+          name: only
+          type: string
+          description: |-
+            Allows basic filtering of events returned. Supply ``hightlight``
+            to return only events where the notification had the highlight
+            tweak set.
+          required: false
+          x-example: "highlight"
+      responses:
+        200:
+          description: A batch of events is being returned
+          examples:
+            application/json: |-
+              {
+                "next_token": "abcdef",
+                "notifications": {
+                  "actions": [
+                    "notify"
+                  ],
+                  "profile_tag", null,
+                  "read", true,
+                  "room_id", "!abcdefg:example.com",
+                  "ts", "1475508881945",
+                  "event", {
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              next_token:
+                type: string
+                description: |-
+                  The token to supply in the ``from`` param of the next
+                  ``/notifications`` request in order to request more
+                  events.
+              notifications:
+                type: array
+                items:
+                  type: object
+                  title: notification
+                  properties:
+                    actions:
+                      type: array
+                      description: |-
+                        The action(s) to perform when the conditions for this rule are met.
+                        See `Push Rules: API`_.
+                      items:
+                        type: any
+                    event:
+                      type: object
+                      title: Event
+                      description: The Event object for the event that triggered the notification.
+                      allOf:
+                        - "$ref": "definitions/event.yaml"
+                    profile_tag:
+                      type: string
+                      description: The profile tag of the rule that matched this event.
+                    read:
+                      type: boolean
+                      description: |-
+                        Indicates whether the user has sent a read receipt indicating
+                        that they have read this message.
+                    room_id:
+                      type: string
+                      description: The ID of the room in which the event was posted.
+                    ts:
+                      type: number
+                      description: |-
+                        The unix timestamp at which the event notification was sent,
+                        in seconds.
+                description: The list of events that triggered notifications.
+      tags:
+        - Notifications API
diff --git a/specification/modules/push.rst b/specification/modules/push.rst
index ba98ea44..58c816b3 100644
--- a/specification/modules/push.rst
+++ b/specification/modules/push.rst
@@ -107,6 +107,15 @@ There is a single API endpoint for this, as described below.
 
 .. _pushers: `def:pushers`_
 
+Listing Notifications
+~~~~~~~~~~~~~~~~~~~~~
+
+A client can retrieve a list of events that it has been notified about. This
+may be useful so that users can see a summary of what important messages they
+have received.
+
+{{notifications_cs_http_api}}
+
 Push Rules
 ~~~~~~~~~~
 A push rule is a single rule that states under what *conditions* an event should