From 25c5bf999600ab04875be5cbd1d47817ae5dd7e2 Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 2 Oct 2025 14:58:27 +1000 Subject: [PATCH 01/10] Update device type documentation to support Firebase --- openapi/paths/api@register@{provider}.yaml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 66b13ced..8ee08f52 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -10,17 +10,16 @@ post: description: | The type of device that is connecting to the service. - As of this version, this is expected to always be "Digistorm". Apple - (APNS) or Google Android (GCM) are still supported, but deprecated: the - Digistorm provider will handle the sending of notifications via APNS or - GCM internally. + As of this version, this is expected to always be "Firebase". Apple + (APNS), Google Android (GCM), or Digistorm remain supported. required: true - example: 'Digistorm' + example: 'Firebase' schema: type: string enum: - GCM - APNS + - Firebase - Digistorm requestBody: $ref: ../components/requestBodies/registration.yaml From f0f179ca600390f923562559c24fc707c834d942 Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 2 Oct 2025 15:02:03 +1000 Subject: [PATCH 02/10] Document mobile device deregister endpoint --- .../requestBodies/mobile-deregistration.yaml | 19 ++++++++++ openapi/paths/api@register@{provider}.yaml | 38 +++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 openapi/components/requestBodies/mobile-deregistration.yaml diff --git a/openapi/components/requestBodies/mobile-deregistration.yaml b/openapi/components/requestBodies/mobile-deregistration.yaml new file mode 100644 index 00000000..e68096d3 --- /dev/null +++ b/openapi/components/requestBodies/mobile-deregistration.yaml @@ -0,0 +1,19 @@ +description: | + The device registration information to remove (Firebase only). + + Requires JSON content type. +content: + application/json: + schema: + type: object + properties: + token: + description: The device token to deregister + type: string + appId: + description: The app identifier + type: string + required: + - token + - appId + diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 8ee08f52..6a2f8dab 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -31,3 +31,41 @@ post: default: $ref: ../components/responses/problem.yaml +delete: + operationId: mobileDeregister + tags: [mobile] + summary: Deregister mobile device + security: [] + description: | + Removes a registered device from receiving push notifications. + parameters: + - name: provider + in: path + description: | + The type of device that is connecting to the service. + + Only "Firebase" is currently supported for deregistration. + required: true + example: 'Firebase' + schema: + type: string + enum: + - Firebase + requestBody: + $ref: ../components/requestBodies/mobile-deregistration.yaml + responses: + '200': + description: Device successfully deregistered + content: + text/plain: + schema: + type: string + '404': + description: Unable to find app registration + content: + application/problem+json: + schema: + $ref: ../components/schemas/problem.yaml + default: + $ref: ../components/responses/problem.yaml + From 2b07f3172a2ae4b5ae21a60e83b5b3607260cfcd Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 14:51:54 +1100 Subject: [PATCH 03/10] Improve schema description --- openapi/components/requestBodies/mobile-deregistration.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/components/requestBodies/mobile-deregistration.yaml b/openapi/components/requestBodies/mobile-deregistration.yaml index e68096d3..ee89b8b7 100644 --- a/openapi/components/requestBodies/mobile-deregistration.yaml +++ b/openapi/components/requestBodies/mobile-deregistration.yaml @@ -1,5 +1,5 @@ description: | - The device registration information to remove (Firebase only). + Request body for deregistering a device from receiving push notifications. Requires JSON content type. content: From 27e628f68d37d1ec199d8b7f7f01a9af3cca1d21 Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 14:52:07 +1100 Subject: [PATCH 04/10] Correct for actual response code --- openapi/paths/api@register@{provider}.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 6a2f8dab..f80805af 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -60,7 +60,7 @@ delete: text/plain: schema: type: string - '404': + '400': description: Unable to find app registration content: application/problem+json: From 785c7e7d12bb7992a72750157c1e0629ae1c671c Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 15:02:15 +1100 Subject: [PATCH 05/10] Updated error statuses to be more acurate --- openapi/paths/api@register@{provider}.yaml | 24 +++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index f80805af..e05cfca0 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -26,6 +26,14 @@ post: responses: '201': $ref: ../components/responses/authentication-successUser.yaml + '400': + description: | + This error occurs when the registration request cannot be processed due to a missing or invalid parameter. + content: + text/plain: + schema: + type: string + example: "Invalid provider: 'invalid_slug'. Accepted providers are: APNS, GCM, Digistorm, Firebase" '401': $ref: ../components/responses/authentication-failed.yaml default: @@ -61,11 +69,21 @@ delete: schema: type: string '400': - description: Unable to find app registration + description: | + This error occurs when the deregistration request cannot be processed. Common causes include: + - An unsupported provider specified in the path parameter + - No matching registration found for the provided device token and app ID combination content: - application/problem+json: + text/plain: schema: - $ref: ../components/schemas/problem.yaml + type: string + examples: + invalidProvider: + summary: Invalid provider + value: "Invalid provider: 'invalid_slug'. Accepted providers are: APNS, GCM, Digistorm, Firebase" + notFound: + summary: Registration not found + value: "Unable to find app registration" default: $ref: ../components/responses/problem.yaml From 660846a1494780f86ed9eb288dfc08edd40138ce Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 15:06:58 +1100 Subject: [PATCH 06/10] clarify wording around supported providers --- openapi/paths/api@register@{provider}.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index e05cfca0..3b6bdc6e 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -8,10 +8,9 @@ post: - name: provider in: path description: | - The type of device that is connecting to the service. + The provider that will handle the sending of push notifications to the device. - As of this version, this is expected to always be "Firebase". Apple - (APNS), Google Android (GCM), or Digistorm remain supported. + While Apple (APNS) and Google Android (GCM) are deprecated, both providers continue to be supported. required: true example: 'Firebase' schema: From c9d61d4c720812a6fdaf6523d9ad9ec597c037c7 Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 15:08:03 +1100 Subject: [PATCH 07/10] add other providers to deregister --- openapi/paths/api@register@{provider}.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 3b6bdc6e..057ba513 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -57,7 +57,10 @@ delete: schema: type: string enum: + - GCM + - APNS - Firebase + - Digistorm requestBody: $ref: ../components/requestBodies/mobile-deregistration.yaml responses: From e00b0ded1c56f75480487dcccf4984e3e7ac449a Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 15:12:45 +1100 Subject: [PATCH 08/10] cleanup wording --- openapi/paths/api@register@{provider}.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 057ba513..13446686 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -10,7 +10,7 @@ post: description: | The provider that will handle the sending of push notifications to the device. - While Apple (APNS) and Google Android (GCM) are deprecated, both providers continue to be supported. + While Apple (APNS) and Google Android (GCM) are still supported, they are deprecated. required: true example: 'Firebase' schema: From f1291099090cb48e009fa7a380a3722508a06f84 Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 15:24:50 +1100 Subject: [PATCH 09/10] add missing body case --- openapi/paths/api@register@{provider}.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 13446686..46e32bc6 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -86,6 +86,9 @@ delete: notFound: summary: Registration not found value: "Unable to find app registration" + missingBody: + summary: Missing request body + value: "We should have done something before this..." default: $ref: ../components/responses/problem.yaml From e37f7821906c1225efc1e2f677abd8f275f2650c Mon Sep 17 00:00:00 2001 From: Bashir <37988348+Brahmah@users.noreply.github.com> Date: Thu, 16 Oct 2025 15:27:55 +1100 Subject: [PATCH 10/10] more examples --- openapi/paths/api@register@{provider}.yaml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/openapi/paths/api@register@{provider}.yaml b/openapi/paths/api@register@{provider}.yaml index 46e32bc6..5b0e966e 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -32,7 +32,22 @@ post: text/plain: schema: type: string - example: "Invalid provider: 'invalid_slug'. Accepted providers are: APNS, GCM, Digistorm, Firebase" + examples: + invalidProvider: + summary: Invalid provider + value: "Invalid provider: 'invalid_slug'. Accepted providers are: APNS, GCM, Digistorm, Firebase" + application/json: + schema: + type: object + properties: + required: + type: string + description: Error message indicating required fields + examples: + missingCredentials: + summary: Missing authentication credentials + value: + required: "Either the \"username\" and \"password\" or the \"jwt\" POST fields must be set" '401': $ref: ../components/responses/authentication-failed.yaml default: