Merge pull request #308 from matrix-org/dbkr/get_pushers

Add endpoint for getting a user's pushers

api/client-server/pusher.yaml

@@ -18,6 +18,96 @@ securityDefinitions:
     name: access_token
     in: query
 paths:
+  "/pushers":
+    get:
+      summary: Gets the current pushers for the authenticated user
+      description: |-
+          Gets all currently active pushers for the authenticated user
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The pushers for this user
+          examples:
+            application/json: |-
+              {
+                "pushers": [
+                  {
+                    "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
+                    "kind": "http",
+                    "app_id": "face.mcapp.appy.prod",
+                    "app_display_name": "Appy McAppface",
+                    "device_display_name": "Alice's Phone",
+                    "profile_tag": "xyz",
+                    "lang": "en-US",
+                    "data": {
+                        "url": "https://example.com/_matrix/push/v1/notify"
+                    }
+                  }
+                ]
+              }
+          schema:
+            type: object
+            properties:
+              pushers:
+                type: array
+                title: Pushers
+                description: |-
+                  An array containing the current pushers for the user
+                items:
+                  type: object
+                  title: Pusher
+                  properties:
+                    pushkey:
+                      type: string
+                      description: |-
+                        This is a unique identifier for this pusher. See `/set` for
+                        more detail.
+                        Max length, 512 bytes.
+                    kind:
+                      type: string
+                      description: |-
+                        The kind of pusher. ``"http"`` is a pusher that
+                        sends HTTP pokes.
+                    app_id:
+                      type: string
+                      description: |-
+                        This is a reverse-DNS style identifier for the application.
+                        Max length, 64 chars.
+                    app_display_name:
+                      type: string
+                      description: |-
+                        A string that will allow the user to identify what application
+                        owns this pusher.
+                    device_display_name:
+                      type: string
+                      description: |-
+                        A string that will allow the user to identify what device owns
+                        this pusher.
+                    profile_tag:
+                      type: string
+                      description: |-
+                        This string determines which set of device specific rules this
+                        pusher executes.
+                    lang:
+                      type: string
+                      description: |-
+                        The preferred language for receiving notifications (e.g. 'en'
+                        or 'en-US')
+                    data:
+                      type: object
+                      description: |-
+                        A dictionary of information for the pusher implementation
+                        itself.
+                      title: PusherData
+                      properties:
+                        url:
+                          type: string
+                          description: |-
+                            Required if ``kind`` is ``http``. The URL to use to send
+                            notifications to.
+      tags:
+        - Push notifications
   "/pushers/set":
     post:
       summary: Modify a pusher for this user on the homeserver.
@@ -40,6 +130,7 @@ paths:
                 "kind": "http",
                 "app_display_name": "Mat Rix",
                 "device_display_name": "iPhone 9",
+                "profile_tag": "xxyyzz",
                 "app_id": "com.example.app.ios",
                 "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
                 "data": {
@@ -79,6 +170,11 @@ paths:
                 description: |-
                   A string that will allow the user to identify what device owns
                   this pusher.
+              profile_tag:
+                type: string
+                description: |-
+                  This string determines which set of device specific rules this
+                  pusher executes.
               lang:
                 type: string
                 description: |-