The purpose of this API is three-fold:

1. Shorten development time by providing a reliable, plug-in solution for alarm functionality
2. Insulate your operation from the intricacies of time calculations, especially as involve DST, time zones, and calibration against time reporting errors
3. Expand app capability by providing additional features which would not otherwise have been made available

#Discussion

##Terminology

• Target refers to the recipient of the Alarm, typically a mobile device such as an iPhone (but conceivably anything against which time is reckoned).
• Trigger refers to the cause->effect link of an Alarm, specifically the conditions which cause the alarm to go off (ie a point in time being reached) and the action taken at that point (sending an email, etc).

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:

1. Get a /token
2. /add a trigger for the time. This would require:
   1. the token for your target from step 1,
   2. the fire_date of “Monday, 1 January 20-- 00:00:00 -000” (the official “new years” release date, formatted for RSS), and
   3. the action 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:

1. Get a /token.
2. Use this token to /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
   1. the token from step 1,
   2. the wall_clock time requested, or 540 (since 9am = 9*60 = 540),
   3. the local_time of “Monday, 31 July 20-- 08:23:14 -600” (the current date in our example on the target formatted for RSS),
   4. the time_zone of “America/Chicago”,
   5. the repeat_mode_indexes array, in this case {5} (since MTWHFSU => 0-6 in the API), and
   6. the action dictionary.
   7. Note that 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.
3. Should our device’s local time zone change (amongst other possible changes), we can always /update these values using the token from step 1 and the new information.
4. Should we need to refresh our local knowledge of which triggers are currently registered for our target, we can always /list them, again with the same token.
5. If we wish to cancel the trigger, we can easily /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

• Input none
• Return JSON success dictionary, with extra key token

##/v1/trigger/add

• Input 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 dictionary
• Return JSON success dictionary, with extra key id

##/v1/trigger/update

• Input token, [local_time and time_zone]
• Return JSON success dictionary

##/v1/trigger/list

• Input token
• Return JSON success dictionary, with extra key triggers value array of triggers as dictionaries with keys: token, id, fire_date, wall_clock , repeat_index, time_zone, action

##/v1/trigger/remove

• Input token, [id]
• Return JSON success dictionary

#Arguments

• JSON success dictionary: contains either success => TRUE or success => FALSE and an error => string; other keys as noted
• token: 64 length alphanumeric string uniquely identifying a target
• local_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:
  • (on input) either a UTC Unix timestamp int or an RSS format date (see local_time)
  • (on output) UTC Unix timestamp int
• repeat_index: 0-6 for M-U or NULL for no repeat
• repeat_mode_indexes: array of repeat_index or NULL for no repeat
• id: 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