From 73d6e901ae9555f39bfd8c14c67631c651abe61f Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 11 Apr 2016 17:25:36 +0100 Subject: [PATCH 1/7] Add endpoint for getting a user's pushers Also add profile_tag to the set docs as it was missing --- api/client-server/pusher.yaml | 93 ++++++++++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 1 deletion(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 060c77c1..6b955dbe 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -18,6 +18,91 @@ 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: |- + [ + { + "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: + pushkey: + type: string + description: |- + This is a unique identifier for this pusher. The value you + should use for this is the routing or destination address + information for the notification, for example, the APNS token + for APNS or the Registration ID for GCM. If your notification + client has no such concept, use any unique identifier. + Max length, 512 bytes. + kind: + type: string + description: |- + The kind of pusher to configure. ``"http"`` makes a pusher that + sends HTTP pokes. ``null`` deletes the pusher. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + It is recommended that this end with the platform, such that + different platform versions get different app identifiers. + 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. If ``kind`` is ``http``, this should contain ``url`` + which is the URL to use to send notifications to. + 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 +125,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": { @@ -77,8 +163,13 @@ paths: device_display_name: type: string description: |- - A string that will allow the user to identify what device owns + 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: |- From 27113d71ff33bf2c3096a0116d2434e10c9ad11b Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 11 Apr 2016 17:31:42 +0100 Subject: [PATCH 2/7] Fix indentation --- api/client-server/pusher.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 6b955dbe..0a55bcaf 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -42,8 +42,8 @@ paths: "data": { "url": "https://example.com/_matrix/push/v1/notify" } - } - ] + } + ] schema: type: object properties: From 0f6e414eb625927c4cfcbba8c7408925152b3bfb Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 11 Apr 2016 17:35:56 +0100 Subject: [PATCH 3/7] Fix format (array of objects, not object) --- api/client-server/pusher.yaml | 115 +++++++++++++++++----------------- 1 file changed, 59 insertions(+), 56 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 0a55bcaf..c601f14b 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -45,62 +45,65 @@ paths: } ] schema: - type: object - properties: - pushkey: - type: string - description: |- - This is a unique identifier for this pusher. The value you - should use for this is the routing or destination address - information for the notification, for example, the APNS token - for APNS or the Registration ID for GCM. If your notification - client has no such concept, use any unique identifier. - Max length, 512 bytes. - kind: - type: string - description: |- - The kind of pusher to configure. ``"http"`` makes a pusher that - sends HTTP pokes. ``null`` deletes the pusher. - app_id: - type: string - description: |- - This is a reverse-DNS style identifier for the application. - It is recommended that this end with the platform, such that - different platform versions get different app identifiers. - 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. If ``kind`` is ``http``, this should contain ``url`` - which is the URL to use to send notifications to. - title: PusherData - properties: - url: - type: string - description: |- - Required if ``kind`` is ``http``. The URL to use to send - notifications to. + type: array + items: + type: object + title: Pusher + properties: + pushkey: + type: string + description: |- + This is a unique identifier for this pusher. The value you + should use for this is the routing or destination address + information for the notification, for example, the APNS token + for APNS or the Registration ID for GCM. If your notification + client has no such concept, use any unique identifier. + Max length, 512 bytes. + kind: + type: string + description: |- + The kind of pusher to configure. ``"http"`` makes a pusher that + sends HTTP pokes. ``null`` deletes the pusher. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + It is recommended that this end with the platform, such that + different platform versions get different app identifiers. + 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. If ``kind`` is ``http``, this should contain ``url`` + which is the URL to use to send notifications to. + 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": From 42834340e713ec0f3b6f41c81ade6b13dd43155b Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 11 Apr 2016 17:41:15 +0100 Subject: [PATCH 4/7] Add title to the pushers array --- api/client-server/pusher.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index c601f14b..a7052442 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -46,6 +46,7 @@ paths: ] schema: type: array + title: Pushers items: type: object title: Pusher From 4fafe1ab73d1d1edf0c20007d08b8b1511335fc6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 11 Apr 2016 17:56:38 +0100 Subject: [PATCH 5/7] Return an object as the root element Because otherwise it's impossible to change later --- api/client-server/pusher.yaml | 145 ++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 69 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index a7052442..97054547 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -30,81 +30,88 @@ paths: description: The pushers for this user examples: application/json: |- - [ - { - "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" + { + "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: array - title: Pushers - items: - type: object - title: Pusher - properties: - pushkey: - type: string - description: |- - This is a unique identifier for this pusher. The value you - should use for this is the routing or destination address - information for the notification, for example, the APNS token - for APNS or the Registration ID for GCM. If your notification - client has no such concept, use any unique identifier. - Max length, 512 bytes. - kind: - type: string - description: |- - The kind of pusher to configure. ``"http"`` makes a pusher that - sends HTTP pokes. ``null`` deletes the pusher. - app_id: - type: string - description: |- - This is a reverse-DNS style identifier for the application. - It is recommended that this end with the platform, such that - different platform versions get different app identifiers. - 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 + properties: + pushers: + type: array + title: Pushers + description: |- + An array containing the current pushers for the user + items: type: object - description: |- - A dictionary of information for the pusher implementation - itself. If ``kind`` is ``http``, this should contain ``url`` - which is the URL to use to send notifications to. - title: PusherData + title: Pusher properties: - url: + pushkey: type: string description: |- - Required if ``kind`` is ``http``. The URL to use to send - notifications to. + This is a unique identifier for this pusher. The value you + should use for this is the routing or destination address + information for the notification, for example, the APNS token + for APNS or the Registration ID for GCM. If your notification + client has no such concept, use any unique identifier. + Max length, 512 bytes. + kind: + type: string + description: |- + The kind of pusher to configure. ``"http"`` makes a pusher that + sends HTTP pokes. ``null`` deletes the pusher. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + It is recommended that this end with the platform, such that + different platform versions get different app identifiers. + 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. If ``kind`` is ``http``, this should contain ``url`` + which is the URL to use to send notifications to. + 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": From 4b294b23dede5207defcf34720c7dd8074f5ef7e Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 12 Apr 2016 09:56:24 +0100 Subject: [PATCH 6/7] Tailor descriptions to GET method --- api/client-server/pusher.yaml | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 97054547..04b55717 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -61,23 +61,18 @@ paths: pushkey: type: string description: |- - This is a unique identifier for this pusher. The value you - should use for this is the routing or destination address - information for the notification, for example, the APNS token - for APNS or the Registration ID for GCM. If your notification - client has no such concept, use any unique identifier. + 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 to configure. ``"http"`` makes a pusher that - sends HTTP pokes. ``null`` deletes the pusher. + 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. - It is recommended that this end with the platform, such that - different platform versions get different app identifiers. Max length, 64 chars. app_display_name: type: string @@ -87,7 +82,7 @@ paths: device_display_name: type: string description: |- - a string that will allow the user to identify what device owns + A string that will allow the user to identify what device owns this pusher. profile_tag: type: string @@ -174,7 +169,7 @@ paths: device_display_name: type: string description: |- - a string that will allow the user to identify what device owns + A string that will allow the user to identify what device owns this pusher. profile_tag: type: string From 1a856b53f3994ce92a1d53eecd659c8cc7818d62 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 13 Apr 2016 10:29:57 +0100 Subject: [PATCH 7/7] Remove redundant info & add backticks --- api/client-server/pusher.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 04b55717..d5c01d3a 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -61,7 +61,7 @@ paths: pushkey: type: string description: |- - This is a unique identifier for this pusher. See /set for + This is a unique identifier for this pusher. See `/set` for more detail. Max length, 512 bytes. kind: @@ -98,8 +98,7 @@ paths: type: object description: |- A dictionary of information for the pusher implementation - itself. If ``kind`` is ``http``, this should contain ``url`` - which is the URL to use to send notifications to. + itself. title: PusherData properties: url: