The purpose of this API is three-fold:
#Discussion
Begin by familiarizing yourself with Apple’s APN docs, as they will be relevant to constructing the notifications you pass to the APNaaS API.
APNaaS greatly simplifies the task of sending push notifications and effectively eliminates the need for you to maintain any server infrastructure of your own to have a full-fledged push system for your apps. Everything has been abstracted, and what remains are the bare minimum requirements to actually send a push notification:
The APNaaS API is therefore subdivided into two parts to facilitate both these requirements: the /certificate endpoints and the /session endpoints.
##/certificate
The /certificate endpoints require that you have a correctly configured certificate package prepared and ready to connect to Apple’s service; this is called a “.pem bundle”: it is a password-protected file containing your ssl certificate in the proper format.
To create your .pem bundle, please follow the steps on this tutorial.
The four endpoints for /certificate simply facilitate basic CRUD management of storing your certificates on APNaaS for later use: /add
, /fetch
, /update
, /remove
Of these, the only non-trivial one is /add
, which returns a certificate id
value in its JSON dictionary. This id
must be used in all subsequent calls requiring certificate id
s to reference this unique certificate.
When you must update your .pem bundle (as you must do periodically since they expire), call /update
with the new .pem data.
For security reasons, a .pem’s passphrase
cannot be changed. If you forget the passphrase or it is compromised, you will need to create a new certificate id
and use the new value in any app/server calls to the APNaaS API.
##/session
The /session endpoints allow for notification delivery, and require a certificate .pem bundle be already added to the system.
Once you have added a certificate, and you wish to send a notification, you will need two additional pieces of information:
token
to which the notification will be delivered. This is retrieved on-device and is outside the scope of APNaaS. It should be formatted as a 64 length alphanumeric string, without brackets ("<" and “>”) or spaces.alert
, badge
, and other keys.Prior to delivery of a notification, a delivery session must begin. Prior to beginning a session, it is recommended, but not necessary, that you /preflight
the session.
The preflight protects your process in 3 ways:
id
and passphrase
are valid and match. Since it is possible that either of these conditions could not be met - for example if a certificate was removed for security reasons - a preflight prevents counterproductive transmission attempts./begin
and /deliver
, can also both result in transmission of significant amounts of data to and from your device/server, so a quick preflight check can prevent wasteful, time-consuming processing (especially on a mobile device).Once preflight is complete, /begin
a session. This returns a session id
, to be used in /deliver
, and an array of invalid tokens
previously returned by Apple’s Push Feedback Service (APFS), another part of the APN infrastructure which APNaaS encapsulates.
You should do two things with the tokens
returned by /begin
(if any):
tokens
, andtokens
, to prevent future attempts at delivery.You are now ready to deliver a set of notifications. A given session is associated with one .pem certificate id
, and thus a single app in a single environment (sandbox or production), but multiple notifications can be delivered to multiple devices within a session.
Please ensure that your app, and server, use sandbox .pem bundles in development and production .pem bundles when live.
Call /deliver
with the session id
from /begin
and a suitably assembled array of notifications
.
Each notification
in the array must contain a single device token
or an array of device tokens
, and an aps
dictionary which complies with Apple’s APN spec, cited above.
Once a session has been /deliver
ed, it is no longer valid and cannot be used again.
##Authorization
All endpoints use Mashape’s internal authorization, so simply append the X-Mashape-Authorization
header field to all requests, with your authorization.
#Endpoints
All arguments are via HTTP POST. Optional arguments are in [brackets].
All API endpoints are also available in a JSON version, accessible by appending /json to the /v1 portion of the path, for example /v1/json/certificate/add
. These endpoints accept as their POST body a json-encoded dictionary with the same keys/values as the parameters in their POST counterpart methods.
##/v1/certificate/add
passphrase
, pem
, sandbox
id
##/v1/certificate/fetch
id
, passphrase
pem
and sandbox
##/v1/certificate/update
id
, passphrase
, pem
, sandbox
##/v1/certificate/remove
id
, passphrase
##/v1/session/preflight
id
, passphrase
##/v1/session/begin
id
, passphrase
id
and tokens
##/v1/session/deliver
id
, notifications
#Arguments
aps
: dictionary - corresponding exactly to the Apple APN spec - with optional keys
alert
badge
sound
content-available
custom-identifier
custom-properties
id
JSON success dictionary
: contains either success => TRUE
or success => FALSE
and an error => string
; other keys as notednotifications
: array of notification
notification
dioctionary with keys aps
and token
and/or tokens
passphrase
: the same passphrase used when you created your .pem bundlepem
: binary file data for the .pem bundle, eg from file_get_contents($myPemFilePath)
sandbox
: BOOL indicating whether this is a test/live .pem bundletokens
: array of token
token
: 64 length alphanumeric strings; iOS device token equivalent#Questions?
All endpoints return errors if arguments are missing or malformed. This api is used in multiple shipping apps, and is robust. However, if you do have a problem which you can’t resolve through debugging, email for support at info-at-hubapps-dot-com