The purpose of this API is three-fold:
#Discussion
##Terminology
These terms are not as plain and direct as “device” and “alarm” but they are more conceptually sound.
##Example Flows
###Basic
For the simplest possible case, imagine you have released a countdown app for iPhone which will announce to users when the next big game/movie/book is coming out. Users download the app, and tap the button to “tell me when countdown completes”. Your app then requests, and is granted, push permission by the device to do this. But how do you know when to send the announcement? The only thing you know is that the release is happening on Jan 1 of the new year.
In this case, you would:
/token
/add
a trigger for the time. This would require:
token
for your target from step 1,fire_date
of “Monday, 1 January 20-- 00:00:00 -000” (the official “new years” release date, formatted for RSS), andaction
dictionary, in this case of type callback
or apns
That’s it! Your action will fire, passing the token
and other contextual information specified in the action
to your server, which can then set about the business of sending out the push notification.
###Longer
For a slightly more involved example, consider a reglar alarm clock app. To set an alarm trigger:
/token
./add
a trigger. In this case, we want to set an alarm for “9am every Saturday” regardless of DST or time zone, so that once set, even if the target’s “local time” changes the trigger will always fire at 9am relative to the target. This is known as “wall clock” mode. Such a trigger would require
token
from step 1,wall_clock
time requested, or 540 (since 9am = 9*60 = 540),local_time
of “Monday, 31 July 20-- 08:23:14 -600” (the current date in our example on the target formatted for RSS),time_zone
of “America/Chicago”,repeat_mode_indexes
array, in this case {5} (since MTWHFSU => 0-6 in the API), andaction
dictionary.id
, and other optional arguments are omitted. This operation will return an id
which we can use to uniquely refer to the trigger in the context of the token
./update
these values using the token
from step 1 and the new information./list
them, again with the same token
./remove
either a specific trigger (or set of repeating triggers) with a token
/id
pair, or all triggers for a target by passing only a token
When the time is reached (every saturday at 9am), the action specified in the action
will be taken.
##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].
Alternatively, the same API can be access by prepending ‘/json’ to all endpoints, and encoding all arguments in a JSON dictionary which is made the POST body. For example:
/v1/json/trigger/list
with the JSON dictionary {token
:< your_token >} as the POST body.##/v1/target/token
token
##/v1/trigger/add
token
, [wall_clock
xor fire_date
], [local_time
, time_zone
- necessary for wall-clock mode], [repeat_mode_indexes
- optional for wall-clock mode], [id
- if provided, will replace any existing trigger with this id], action
- JSON action dictionaryid
##/v1/trigger/update
token
, [local_time
and time_zone
]##/v1/trigger/list
token
triggers
value array of triggers as dictionaries with keys: token
, id
, fire_date
, wall_clock
, repeat_index
, time_zone
, action
##/v1/trigger/remove
token
, [id
]#Arguments
JSON success dictionary
: contains either success => TRUE
or success => FALSE
and an error => string
; other keys as notedtoken
: 64 length alphanumeric string uniquely identifying a targetlocal_time
: RSS format (“E, d MMM y HHⓂ️s Z”, PHP’s DateTime::RSS)time_zone
: eg ‘America/New_York’wall_clock
: int referring to wall-clock time, from 0-1439 (for 12:00am to 11:59pm)fire_date
:
local_time
)repeat_index
: 0-6 for M-U or NULL for no repeatrepeat_mode_indexes
: array of repeat_index
or NULL for no repeatid
: 16 length alphanumeric string for identifying this trigger (or set of repeating triggers, which share an id).action
: a JSON dictionary describing the action to be taken when the trigger fires, takes a different form depending on type:If ‘mail’, has keys:
{
type => 'mail'
to
from
subject
body
}
If ‘callback’, has keys:
{
type => 'callback'
url => your url, accepting POST body of JSON containing {token =>, id =>, repeat_index =>, context => < your_context_info >}
context => some custom arbitrary string identifier for this callback, optional
}
If ‘apns’, has keys:
{
type => 'apns'
certificate_id => the 'id' returned from the APNaaS API for your registered .pem certificate
passphrase => the passphrase for accessing your .pem
device_token => 64 length iOS Push device token (sans brackets ("<", ">") or spaces)
aps => {
alert => {
action-loc-key
body
}
badge
content-available
custom-identifier
custom-properties => {
property => value,
...
}
sound
}
}
##Clarifications
wall_clock
vs fire_date
: wall-clock time changes with DST and time zone changes, and can also have a repeat interval, whereas a fixed fire-date is absolute and non-repeating.
repeat_index
: when scheduling a repeating trigger, the first date it will fire will be the next occurence of the wall_clock
time specified on the repeating day specified. Thus, if you schedule a trigger on saturday to repeat every tuesday at 8pm, the trigger will not fire until next tuesday.
id
: IDs are unique only within the scope of a given token
. Even then, while a non-repeating trigger has a unique ID, a repeating trigger is stored (and reported in /list
) as multiple triggers with the same ID which differ by their repeat_index
(and thus fire_date
).
apns
: to use “push” actions (currently iOS only), you must also consume the APNaaS API. Add your certificates to the APNaaS API, and then pass the id
and passphrase
parameters in the apns
part of your action
dictionary when scheduling an alarm (together with the device_token
, which is different from the target token
returned for the alarm trigger in this API.
In this case, it is possible that your alarms may, on occasion, be removed automatically if Apple’s Push Feedback Service indicates that a device token is invalid. If you are properly scheduling and removing alarms following user action, it is unlikely you will experience a conflict here. If, however, you are automatically scheduling push from a service, independent of user action, then this result is “normal”, and the appropriate response to invalid device tokens via APFS.
#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