Merge pull request #396 from matrix-org/dbkr/notifs_api

Spec notifs API

api/client-server/notifications.yaml

@@ -0,0 +1,142 @@
+# 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: query
+          type: string
+          name: from
+          description: Pagination token given to retrieve the next set of events.
+          required: false
+          x-example: "xxxxx"
+        - in: query
+          type: number
+          name: limit
+          description: Limit on the number of events to return in this request.
+          required: false
+          x-example: "20"
+        - in: query
+          name: only
+          type: string
+          description: |-
+            Allows basic filtering of events returned. Supply ``highlight``
+            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": "hcbvkzxhcvb",
+                    "read": true,
+                    "room_id": "!abcdefg:example.com",
+                    "ts": 1475508881945,
+                    "event": {
+                      "sender": "@alice:example.com",
+                      "type": "m.room.message",
+                      "age": 124524,
+                      "txn_id": "1234",
+                      "content": {
+                        "body": "I am a fish",
+                        "msgtype": "m.text"
+                      },
+                      "origin_server_ts": 1417731086797,
+                      "event_id": "$74686972643033:example.com"
+                    }
+                  }
+                ]
+              }
+          schema:
+            type: object
+            required: ["notifications"]
+            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. If this is absent, there are no more results.
+              notifications:
+                type: array
+                items:
+                  type: object
+                  required: ["actions", "event", "read", "room_id", "ts"]
+                  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:
+                        - object
+                        - string
+                    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: integer
+                      description: |-
+                        The unix timestamp at which the event notification was sent,
+                        in milliseconds.
+                description: The list of events that triggered notifications.
+      tags:
+        - Push notifications

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