Howl : A Growl App for iPhone & iPad

Push Notifications from Anywhere

The Howl API is a great way to extend the functionality of Howl past Growl enabled Mac apps to just about anything. The Howl API can be called from scripts, services, or even used to build plugins for generalized notification systems.

The Howl API uses a restful interface over HTTPS. This makes implementing clients in just about any language simple and straightforward. The API can even be called directly from command line tools like curl.

All methods in the Howl API take form parameters as input and return a structured response back in the format of the callers choosing: JSON, XML property list, or binary property list. The response format is determined by the extension appended to the API URL. By default, JSON objects will be returned.

https://howlapp.com/public/api/notification: JSON
https://howlapp.com/public/api/notification.js: JSON
https://howlapp.com/public/api/notification.xml: XML Property List
https://howlapp.com/public/api/notification.plist: Binary Property List

Responses, whether successful or exceptional, all have the same basic structure:

{
  status: status
  payload: {
    payload data
  }
}

A status set to ok means the operation was successful. Any other status value indicates that the request has failed and the payload should be inspected for detailed reasoning. Status names map directly to HTTP status codes, which are also set appropriately when a call fails. The returned structure for a failed request might look like the following:

{
  "status":"bad_request",
  "payload":{
    "code":"InvalidArgumentError",
    "message":"Invalid ticket"
  }
}

While error messages are useful for debugging, the exact values of code and message are not guaranteed to remain unchanged. Developers should rely on the status field and/or HTTP status code to determine the success or failure of the call.

Requirements

Since Howl is designed for personal use, APIs are rate limited per user. A user may make up to 2,000 calls in a 31 day period.

To prevent against rogue scripts, a user must register and verify an email address. Failure to respond to emails regarding excessive or inappropriate use may result in disabled API use for a user or specific device.

Intermediate Certificate

If your software requires StartCom's intermediate certificate, you can download the certificate from startssl.com. Recent versions of cURL do not include this certificate but may provide it in the future.

public/api/notification

notification is used for posting new notifications to any devices enabled for a user. Notifications posted using this API may use a unique icon provided by the caller or one of several pre-defined icons for applications which may not have a contextual image.

Formats

xml, json, plist

HTTP Methods

POST, PUT

Requires Authentication

true

API Rate Limited

true

Parameters

Required

name: The name of the notification. This value not displayed, but is used to categorize a class of notifications within an application.
title: The subject of an application. This should include a relatively short summary of the notification.
description: The text of the notification
application: The name of the application which generated the message. This may or may not be the same as the application calling the API.

Optional

priority

An integer value ranging from -5 to 5 (inclusive).

hostname

The name of the host where the notification was generated.

icon-*

Either a named icon (using the icon-name parameter) or the MD5 and SHA1 digests of an icon the caller should be prepared to upload if necessary (using both the icon-md5 and icon-sha1 parameters).

When using icon-name an icon name from those listed on icons page must be used. If the icon name chosen does not match one of these preconfigured icons, an error will be returned.

When using icon-md5 and icon-sha1, the icon must be:

smaller than 128KiB
in PNG format

Returns

notification will return several one or more keys indicating the status of the message, and whether or not further action is required to provide an icon for the message.

The notification_sent key signifies that the notification was sent successfully. The value of this key, if present, will always be true.

If the application must provide an icon for the notification that was sent, the needs_icon key will be present set to true. An icon_ticket entry will also be present containing a unique key which the application should use to upload the relevant icon. Icons are uploaded with the icon API.

Icon tickets are good for 15 minutes. The icon uploaded with the ticket must have a matching MD5 and SHA1 digests. Failure to upload an icon with the provided ticket will result in a missing icon for the notification until another icon with matching MD5 and SHA1 hashes is uploaded.

Curl Example


  curl \

  -X POST \

  --data name=test \

  --data 'title=Test Notification' \

  --data 'description=here are the details' \

  --data 'application=curl' \

  --data 'icon-md5=dc0f5209059a0e7f3ff298680f98bc1b' \

  --data 'icon-sha1=22339dd6e17eb099ed023c72bd7b5deaf785f2bb' \

  -u 'username:password' \

  https://howlapp.com/public/api/notification

JSON Response

{ 
  "status":"ok",
  "payload":{
    "needs_icon":true,
    "icon_ticket":"C1997EB5-B368-47D3-BDCE-38A2F33B9B56",
    "notification_sent":true
  }
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>status</key>
    <string>ok</string>
    <key>payload</key>
    <dict>
      <key>needs_icon</key>
      <true/>
      <key>icon_ticket</key>
      <string>C1997EB5-B368-47D3-BDCE-38A2F33B9B56</string>
      <key>notification_sent</key>
      <true/>
    </dict>
  </dict>
</plist>

public/api/icon

Formats

xml, json, plist

HTTP Methods

POST, PUT

Requires Authentication

true

API Rate Limited

true

Parameters

Required

ticket: The ticket value returned by a call to notification.
icon: The PNG icon data. This must be unchanged from the data used to calculate the MD5 and SHA1 digests when sending a notification. This must be uploaded as a file form input (multipart/mime).

Returns

icon returns a single key, thanks which confirms that the operation was successful. If the icon was used, thanks will contain the value true. If the icon was no longer necessary, thanks will contain false. This value should not matter to your application. Applications should only be concerned with the presence of the thanks key.

Curl Example


  curl \

  -X PUT \

  --form icon=@howl-128.png \

  --form ticket=C1997EB5-B368-47D3-BDCE-38A2F33B9B56 \

  -u 'username:password' \

  https://howlapp.com/public/api/icon

JSON Response

{
  "status": "ok",
  "payload": {
    "thanks": true
  }
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" 
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>payload</key>
    <dict>
      <key>thanks</key>
      <true/>
    </dict>
    <key>status</key>
    <string>ok</string>
  </dict>
</plist>

Howl A Growl App for iPhone & iPad

Push Notifications from Anywhere

Requirements

Intermediate Certificate

public/api/notification

Formats

HTTP Methods

Requires Authentication

API Rate Limited

Parameters

Returns

Curl Example

JSON Response

XML Response

public/api/icon

Formats

HTTP Methods

Requires Authentication

API Rate Limited

Parameters

Returns

Curl Example

JSON Response

XML Response

Howl
A Growl App for iPhone & iPad