Merge pull request #306 from matrix-org/dbkr/add_push_change_event_id

Change `id` -> `event_id` and include push section

api/push-gateway/push_notifier.yaml

@@ -17,10 +17,23 @@ paths:
       summary: Notify a push gateway about an event.
       description: |-
         This endpoint is invoked by HTTP pushers to notify a push gateway about
-        an event.
-        *NB: Notifications are sent to the URL configured when the pusher is
+        an event or update the number of unread notifications a user has.
+        In the former case it will contain selected information about the event.
+        In either case it may contain numeric counts of the number of unread
+        events of different types the user has. The counts may be sent along
+        with a notification about an event or by themselves.
+
+        Notifications about a particular event will normally cause the user to be
+        alerted in some way. It is therefore necessary to perform duplicate
+        suppression for such notifications using the `event_id` field to avoid
+        retries of this HTTP API causing duplicate alerts. The operation of
+        updating counts of unread notifications should be idempotent and
+        therefore do not require duplicate suppression.
+
+        Notifications are sent to the URL configured when the pusher is
         created. This means that the HTTP path may be different depending on the
-        push gateway.*
+        push gateway.
+
       parameters:
         - in: body
           name: notification
@@ -42,7 +55,6 @@ paths:
                   "content": {
                     "msgtype": "m.text",
                     "body": "I'm floating in a most peculiar way."
-                  }
                   },
                   "counts": {
                      "unread" : 2,
@@ -60,29 +72,41 @@ paths:
                     }
                   ]
                 }
-            required: ["notification", "counts", "devices"]
+              }
+            required: ["notification"]
             properties:
               notification:
                 type: object
+                title: Notification
                 description: Information about the push notification
-                required: ["id", "room_id", "type", "sender"]
+                required: ["devices"]
                 properties:
-                  id:
+                  event_id:
                     type: string
                     description: |-
-                      An identifier for this notification that may be used to
-                      detect duplicate notification requests. This is not
-                      necessarily the ID of the event that triggered the
-                      notification.
+                      The Matrix event ID of the event being notified about.
+                      This is required if the notification is about a
+                      particular Matrix event. It may be omitted for notifications
+                      that only contain updated badge counts. This ID can and
+                      should be used to detect duplicate notification requests.
                   room_id:
                     type: string
-                    description: The ID of the room in which this event occurred.
+                    description: |-
+                      The ID of the room in which this event occurred.
+                      Required if the notification relates to a specific
+                      Matrix event.
                   type:
                     type: string
-                    description: The type of the event as in the event's ``type`` field.
+                    description: |-
+                      The type of the event as in the event's ``type`` field.
+                      Required if the notification relates to a specific
+                      Matrix event.
                   sender:
                     type: string
-                    description: The sender of the event as in the corresponding event field.
+                    description: |-
+                      The sender of the event as in the corresponding event field.
+                      Required if the notification relates to a specific
+                      Matrix event.
                   sender_display_name:
                     type: string
                     description: |-
@@ -116,6 +140,7 @@ paths:
                       event had no content field, this field is omitted.
                   counts:
                     type: object
+                    title: Counts
                     description: |-
                       This is a dictionary of the current number of unacknowledged
                       communications for the recipient user. Counts whose value is
@@ -138,6 +163,7 @@ paths:
                       This is an array of devices that the notification should be sent to.
                     items:
                       type: object
+                      title: Device
                       properties:
                         app_id:
                           type: string

specification/index.rst

@@ -20,6 +20,7 @@ The following APIs are documented in this specification:
 - `Server-Server API <server_server.html>`_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix.
 - `Application Service API <application_service.html>`_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers.
 - `Identity Service API <identity_service.html>`_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs.
+- `Push Gateway API <push_gateway.html>`_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in.
 
 There are also some `appendices <appendices.html>`_.
 

specification/push_gateway.rst

@@ -39,4 +39,4 @@ This describes the format used by "HTTP" pushers to send notifications of
 events to Push Gateways. If the endpoint returns an HTTP error code, the
 homeserver SHOULD retry for a reasonable amount of time using exponential backoff.
 
-{{push_notifier_http_api}}
+{{push_notifier_push_http_api}}

specification/targets.yaml

@@ -22,6 +22,9 @@ targets:
   identity_service:
     files:
       - identity_service_api.rst
+  push_gateway:
+    files:
+      - push_gateway.rst
   appendices:
     files:
       - appendices.rst

templating/matrix_templates/units.py

@@ -21,6 +21,7 @@ HTTP_APIS = {
     "../api/application-service": "as",
     "../api/client-server": "cs",
     "../api/identity": "is",
+    "../api/push-gateway": "push",
 }
 EVENT_EXAMPLES = "../event-schemas/examples"
 EVENT_SCHEMA = "../event-schemas/schema"