diff --git a/openapi/components/requestBodies/mobile-deregistration.yaml b/openapi/components/requestBodies/mobile-deregistration.yaml new file mode 100644 index 00000000..ee89b8b7 --- /dev/null +++ b/openapi/components/requestBodies/mobile-deregistration.yaml @@ -0,0 +1,19 @@ +description: | + Request body for deregistering a device from receiving push notifications. + + 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 66b13ced..5b0e966e 100644 --- a/openapi/paths/api@register@{provider}.yaml +++ b/openapi/paths/api@register@{provider}.yaml @@ -8,27 +8,102 @@ 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 "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. + While Apple (APNS) and Google Android (GCM) are still supported, they are deprecated. required: true - example: 'Digistorm' + example: 'Firebase' schema: type: string enum: - GCM - APNS + - Firebase - Digistorm requestBody: $ref: ../components/requestBodies/registration.yaml 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 + 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: $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: + - GCM + - APNS + - Firebase + - Digistorm + requestBody: + $ref: ../components/requestBodies/mobile-deregistration.yaml + responses: + '200': + description: Device successfully deregistered + content: + text/plain: + schema: + type: string + '400': + 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: + text/plain: + schema: + 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" + missingBody: + summary: Missing request body + value: "We should have done something before this..." + default: + $ref: ../components/responses/problem.yaml +