API Reference
This document details the APIs exposed by notification manager for subscription management and publishes.
Authorization
All APIs MUST be digitally signed by adding an appropriate JSON Web Token (JWT) in the Authorization
header. Each API has a specific criteria for validation.
APIs
SPECIAL HTTP RESPONSE CODES
| Code | Description |
|---|---|
| 452 | DB read Error |
| 453 | DB write Error |
| 454 | DB delete Error |
| 455 | DB field Error |
NTM ERROR CODES
| Code | Description | Possible HTTP Response codes |
|---|---|---|
| NTM-0000 | Initial JWT validation failed | 401 |
| NTM-0001 | JWT claims type unauthorized | 401 |
| NTM-0002 | JWT claims scope unauthorized | 401 |
| NTM-0003 | Unable to parse request | 400 |
| NTM-0004 | Validation failures based on input in request | 400 |
| NTM-0005 | unable to complete request | 452, 453, 454, 455 |
| NTM-0006 | cached core Jwt related error | 500 |
GET /v1/subscriber/:id
Description
This API retrieves subscriber information including all subscriptions identified by subscriberID.
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "core" or "server" with scope "readwrite:ntm"
Request
Pass the following as path parameter
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
id string Subscriber ID
Response
200 OK and the following stringified JSON
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
appDomain string app domain
appDomainClientID string client ID
proto string one of {"xmpp", "apns", "gcm", "fcm" , "webn"}
token string device token (if proto is "apns" or "gcm")
callbackURL string callback URL for "webn" subscriber
subscriptions array JSON objects each object contains key-values pertinent to a subscription
- 4XX, 5XX
GET /v2/subscriber/proto/:proto/token/:token
Description
This API retrieves subscriber information including all subscriptions
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "core", "server" or "client"
Request
Pass the following as parameter
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
proto string one of {"xmpp", "apns", "gcm", "fcm" , "webn"}
token string device token (when proto is "apns" or "gcm") or routingID (when proto is "xmpp" or "webn")
Response
200 OK and the following stringified JSON
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
appDomain string app domain
appDomainClientID string client ID
proto string should be same as what is provided in query
token string should be same as what is provided in query
callbackURL string callback URL for a "webn" subscriber
subscriptions array JSON objects each object contains key-values pertinent to a subscription
- 4XX, 5XX
GET /v1/subscribers/topic/:topic
Description
This API retrieves subscribers information for a specific subscription topic
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "core" or "server" with scope "readwrite:ntm"
Request
Pass the following as parameter
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
topic string URL encoded topic
Response
200 OK and the following stringified JSON
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
apnTopic string apn topic, if present
preferences string preferences, if present
subscribers array JSON objects each object contains key-values pertinent to a subscriber
- 4XX, 5XX
POST /v1/subscriber
Description
This API allows subscribers to register. This API is idempotent - if the API is called with the
same set of inputs, the same subscriber ID will be returned
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "server" OR "client" with scope "readwrite:ntm"
- App domain in JWT claims MUST match one in request payload
- "app_domain_client_id" will be extracted from JWT
- Content-Type associated with request payload MUST be either *application/json* or *application/x-www-form-urlencoded*
No other format is supported
Request
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
app_domain string (MANDATORY) Application domain (Ex: cox.comcast.net")
proto string (MANDATORY) "apns", "gcm", "fcm", "xmpp" or "webn" ONLY
token string (MANDATORY) for apns and gcm, this is device specific. For xmpp,
is a routing ID. The routing ID MUST match routing ID derived from
user_id in client JWT
callback_url string (Optional) If the protocol is "webn" a callbackURL for webhook MUST be supplied.
Response
200 OK and the following stringified JSON
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
id string subscriber ID
- 4XX, 5XX
POST /v1/subscription/subscriber/:id/topic/:topic
Description
This API allows subscribers to subscribe to a topic. When a subscription is tied to IOS device
then the apns_topic of the remote notification, which is typically the bundle ID for the IOS app,
MUST be passed in the request body
Note: apn_topic or preferences can be changed when subscriptions are added
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "server" OR "client" with scope "readwrite:ntm"
- For a client JWT, RoutingID extracted from JWT claims MUST match the routingID in topic
- Content-Type associated with request paylod MUST be *application/json*. No other format is
supported
Request
Pass the following as path parameters
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
id string (MANDATORY) Subscriber ID
topic string (MANDATORY) URL encoded topic (Not to be confused with bundle ID for IOS APP)
associated with the application
If apn topic is to be provisioned for this subscription, pass it in the request body as a JSON object.
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
apn_topic string (OPTIONAL) Typically, the bundle ID for an IOS APP
preferences stringfied JSON (OPTIONAL) Typically, notification preferences for IOS and Android devices
Response
200
4XX, 5XX
POST /v1/publish
Description
This API allows an external server to publish a Notification for a supplied topic. All the subscribers
with active subscriptions will be notified with the relayed payload.
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "server" only
- Content-Type associated with request payload MUST be *application/json*
Request
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
topic string (MANDATORY) Subscription topic
data JSON (MANDATORY) The push message that will be passed as-is in the Notification
preferences JSON (Optional) This is an optional JSON that overrides the topic level Preferences.
and governs delivery QoS and message formatting for mobile notifications.
The Preferences structure controls delivery and message formatting parameters in APNs and FCM. Preferences are applied only for mobile notifications.
----------------------------------------------------------------------------------------------
Preference Type Description
----------------------------------------------------------------------------------------------
priority string (MANDATORY) Subscription topic
ttl int (MANDATORY) The push message that will be passed as-is in the Notification
silent bool Controls if notification is silent
badge int notification badge count
alert string/JSON the alert field in aps dictionary
category string the notification category
sound string name of the sound file from application resource bundle
Response
200 OK
- 4XX, 5XX
DELETE /v1/subscription/subscriber/:id/topic/:topic
Description
This API allows subscribers to unsubscribe to a topic.
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "server" OR "client" with scope "readwrite:ntm"
Request
Pass the following as path parameters
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
id string Subscriber ID
topic string URL encoded topic
Response
200
4XX, 5XX
DELETE /v1/subscriber/:id
Description
This API allows for a subscriber to unregister
- API Authentication
- JWT signature verification
- JWT claims expiration time validation
- JWT claims type MUST be "server" OR "client" with scope "readwrite:ntm"
Request
Pass the following as parameters
----------------------------------------------------------------------------------------------
Property Type Description
----------------------------------------------------------------------------------------------
id string Subscriber ID
Response
200
4XX, 5XX