View Source HTTP API

If for some reason you need Swagger specs for this RESTful service, there is a swagger endpoint available via an HTTP path /swagger.json

Request

There is only one endpoint at the moment:

  • POST /{version}/notification/{device_id}

As you can imagine, {device_id} should be replaced with a device ID/Token generated by your push notification provider (FCM or APNS). The notification should be sent as a JSON payload of this request. A minimal JSON request could be like this:

{
  "service": "apns",
  "alert":
    {
      "body": "notification's text body",
      "title": "notification's title"
    }
}

The full list of options contains the following:

  • service (required, apns or fcm) - push notifications provider to be used for this notification
  • mode (optional, prod (default) or dev) - allows for selecting named pool configured in MongoosePush
  • priority (optional) - Either normal or high. Those values are used without changes for FCM. For APNS however, normal maps to priority 5, while high maps to priority 10. Please refer to FCM / APNS documentation for more details on those values. By default priority is not set at all, therefore the push notification service decides which value is used by default.
  • time_to_live (optional) - Maximum lifespan of an FCM notification. For more details, please, refer to the official FCM documentation.
  • mutable_content (optional, true / false (default)) - Only applicable to APNS. Sets "mutable-content=1" in the APNS payload.
  • topic (optional, APNS specific) - if the APNS certificate configured in MongoosePush allows for multiple applications, this field selects the application. Please refer to the APNS documentation for more details.
  • tags (optional) - a list of tags used to choose a pool with matching tags. To see how tags work read: https://github.com/esl/sparrow#tags
  • data (optional) - custom JSON structure sent to the target device. For APNS, all keys from this structure are merged into the highest level APS message (the one that holds the 'aps' key), while for FCM the whole data json structure is sent as FCM's data payload along with notification.
  • alert (optional) - JSON structure that if provided will send a non-silent notification with the following fields:
    • body (required) - text body of the notification
    • title (required) - short title of the notification
    • click_action (optional) - for FCM its activity to run when notification is clicked. For APNS its category to invoke. Please refer to the Android/iOS documentation for more details about this action
    • tag (optional, FCM specific) - notifications aggregation key
    • badge (optional, APNS specific) - unread notifications count
    • sound (optional) - sound that should be play when the notification arrives. Please refer to the FCM / APNS documentation for more details.

Please note that either alert and data has to be provided (also can be both). If you only specify alert, the request will result in a classic, simple notification. If you only specify data, the request will result in a "silent" notification, i.e. the client will receive the data and will be able to decide whether and how the notification should be shown to the user. If you specify both alert and data, the target device will receive both notification and the custom data payload to process.

Response

Description of the possible server responses

  • 200 "OK" - the request was successful.
  • 400 {"reason" : "invalid_request"|"no_matching_pool"} - the request was invalid.
  • 410 {"reason" : "unregistered"} - the device was not registered.
  • 413 {"reason" : "payload_too_large"} - the payload was too large.
  • 429 {"reason" : "too_many_requests"} - there were too many requests to the server.
  • 503 {"reason" : "service_internal"|"internal_config"|"unspecified"} - the internal service or configuration error occurred.
  • 520 {"reason" : "unspecified"} - the unknown error occurred.
  • 500 {"reason" : reason} - the server internal error occurred, specified by reason.