The purpose of this API is three-fold:

1. Shorten development time by providing a reliable, plug-in solution for APN functionality
2. Insulate your operation from the intricacies of push hosting and implementation, especially as regards connections, deliver, and errors
3. Expand app capability by providing additional features which would not otherwise have been made available

#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:

1. the ssl certificate used to connect to Apple’s APN service
2. the notifications which you are sending, and to which devices

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 ids 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:

1. the device 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.
2. the aps payload to be delivered. This is exactly as formatted in Apple’s docs, with 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:

1. It serves to assure that the certificate 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.
2. The other methods, /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).
3. If you are adding a token and criteria to your own server for later delivery - for example, if a device is registering to receive weather updates over time - a preflight can serve to ensure that the credentials to be stored are valid at the time of registration, rather than when push delivery is attempted and errors cannot be caught and corrected.

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):

1. Remove any notifications you planned on delivering when you began the session which use the invalid tokens, and
2. Remove any entries in your database which reference the invalid tokens, 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 /delivered, 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

• Input passphrase, pem, sandbox
• Return JSON success dictionary, with extra key certificate id

##/v1/certificate/fetch

• Input certificate id, passphrase
• Return JSON success dictionary, with extra keys pem and sandbox

##/v1/certificate/update

• Input certificate id, passphrase, pem, sandbox
• Return JSON success dictionary

##/v1/certificate/remove

• Input certificate id, passphrase
• Return JSON success dictionary

##/v1/session/preflight

• Input certificate id, passphrase
• Return JSON success dictionary

##/v1/session/begin

• Input certificate id, passphrase
• Return JSON success dictionary, with extra keys session id and tokens

##/v1/session/deliver

• Input session id, notifications
• Return JSON success dictionary

#Arguments

• aps: dictionary - corresponding exactly to the Apple APN spec - with optional keys
  • alert
  • badge
  • sound
  • content-available
  • custom-identifier
  • custom-properties
  • any other keys you add will be added as-is to the aps payload
• id
  • certificate: 64 length alphanumeric string
  • session: 64 length alphanumeric string
• JSON success dictionary: contains either success => TRUE or success => FALSE and an error => string; other keys as noted
• notifications: array of notification
  • notification dioctionary with keys aps and token and/or tokens
• passphrase: the same passphrase used when you created your .pem bundle
• pem: binary file data for the .pem bundle, eg from file_get_contents($myPemFilePath)
• sandbox: BOOL indicating whether this is a test/live .pem bundle
• tokens: 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