Contents

Endpoint	Description
/apps	Manages application registrations
/authorise	Generates an access_token that allows access to the rest of the API
/events	Manages application event creations and deletions
/notifications	Manages notifications
/info	Returns information about the running instance of Snarl

/apps

This endpoint manages application registrations. Your application can register multiple applications with Snarl, however typically it would only ever register one.

Method	Function	Description
POST	/apps	Registers an application
DELETE	/apps/:appId	Unregisters an application
GET	/apps/:appId	Returns an application which contains information about the specified application

POST /apps

Registers an application with Snarl.

Path Arguments

None

Data Arguments

Name	Status	Description
app-id	Required	The (application identifier) to use.
title	Required	The application’s name as displayed to the end user.
hint	Optional	Free-form hint text that describes the application to the end user.
icon	Optional	The icon to use, this can be any of the standard (Snarl API icon types).

Response

If the application was registered successfully, you’ll get a success response with the application’s identifier included. If the application wasn’t registered successfully, you’ll get a failed response with suitable error information.

Possible reasons for failure include:

• An application with the same identifier is already registered with a different access_token
• Either of the title or app-id parameters were missing or invalid
• No access token was provided

Example

curl http://ninja:4444/v2/apps?access_token=00000001 -d "{ 'app-id': 'myapp', 'title': 'My App' }"

{
  "success": {
    "app-id": "myapp"
  }
}

DELETE /apps/{app-id}

Unregisters an application.

Required Arguments

Name	Description
app-id	The application identifier for the registration to delete.

Optional Arguments

None.

Response

If the application was unregistered successfully, you’ll get a success response with the application’s identifier included. If the application wasn’t unregistered successfully, you’ll get a failed response with suitable error information.

Possible reasons for failure include:

• The application isn’t registered
• The application was registered with a different access_token
• The app-id parameter was missing or invalid
• No access token was provided

Example

curl -X DELETE http://ninja:4444/v2/apps/myapp?access_token=00000001

{
  "success": {
    "app-id": "my app"
  }
}

GET /apps

Retrieves a list of all applications registered using the provided access_token.

Arguments

None.

Response

If successful, you’ll get a Success object that contains an Applications object which lists all the registrations you’ve made. If you’ve not made any registrations, you’ll still get the Applications object, only it will be empty.

If the request fails, you’ll get a (failed) response with suitable error information. Possible reasons for failure include:

• No access token was provided
• An invalid access token was provided

GET /apps/{app-id}

Returns information about a previously registered application

Example

curl http://ninja:4444/v2/apps/myapp?access_token=00000001

Response

If the application is registered, you’ll get a success response that contains an application object which describes the application. If the application wasn’t registered successfully, you’ll get a (failed) response with suitable error information. Possible reasons for failure include:

• The application isn’t registered
• No access token was provided
• The application was registered using a different access token, or a different transport

---

/authorise

This endpoint manages authenticating clients. At this time it only exposes a single function, the endpoint itself.

GET /authorise

Generates an access_token so the calling application can access the rest of the API.

Response

If authentication was successful, you’ll get a success object returned with the access_token included.

Example

{
  "success": {
    "access_token": "3fd94a8e-3add-48ec-ac29-649c9a2576a4"
  }
}

---

/events

Manages notification event classes. The following functions are defined:

Method	Function	Description
POST	/events/:appId	Adds one or more events to an application
DELETE	/events/:appId/:eventId	Removes a specific event class from an application
DELETE	/events/:appId	Removes all events from the specified application
GET	/events/:appId	Returns an events object which contains details of the event classes assigned to the specified application

POST /events/:appId

Adds one or more events to the application specified by :appId. If a particular event exists, it will be updated with any new information provided.

Path Arguments

Name	Status	Description
:appId	Required	Application identifier.

Data Arguments

Name	Status	Description
events	Required	A completed events object containing the event classes to add or update.

Response

Returns 200 if all events were added or updated successfully, or one of the following errors:

Status Code	Likely cause
400	Incorrectly formatted data or at least one event object missing an event-id parameter
401	Transport authentication or application password protection mismatch
404	Application :appId not registered

Note that any classes that were added will remain, but processing of further events will stop.

Example

curl -H "Content-Type: application/json" "http://192.168.1.110:8080/v2/events/app" -d '{ "events": [ { "event-id": "foo", "name": "Event Foo" } ] }'

{
  "success": {}
}

GET /events/:appId

Returns the events associated with the application specified by :appId.

Required Arguments

Name	Description
app-id	The application identifier to retrieve information on.

Optional Arguments

None.

Response

If the information was retrieved a success object with an application object included. If an error occurs, a failed object will be returned.

Possible reasons for failure include:

• The specified application wasn’t registered using the provided access_token.

Example

x

{
  "success": {
    "app-id": "my app"
  }
}

DELETE /events/{app-id}/{event-id}

Removes the event with {event-id} from registration {app-id}.

Required Arguments

Name	Description
app-id	The application identifier to retrieve information on.
event-id	The event identifier to retrieve information on.

Optional Arguments

None.

Response

N.

Possible reasons for failure include:

• N

Example

x

{
  "success": {
    "app-id": "my app"
  }
}

---

/notifications

This endpoint manages notifications.

        // POST    /v2/notifications/:appId[/:eventId]
        // GET     /v2/notifications/:appId[/:eventId]
        // GET     /v2/notifications/:guid
        // DELETE  /v2/notifications/:guid

Method	Function	Description
POST	/notifications/[:appId[/:eventId]]	Displays a notification

POST /notifications/[:appId[/:eventId]]

Creates a new notification.

Path Arguments

Name	Status	Description
:appId	Optional	Application identifier.
:eventId	Optional	Event identifier.

Data Arguments

Name	Status	Description
callback-dismissed	Optional	A (managed callback) to process if the user dismisses the notification
callback-expired	Optional	A (managed callback) to process if the notification expires without any user interaction
callback-invoked	Optional	A (managed callback) to process if the user invokes the notification
duration	Optional	The number of seconds the notification should be displayed on-screen for
icon	Optional*	The notification icon - this can be any (standard Snarl icon)
password	Optional	Password used during application registration, if one was provided
priority	Optional	The notification priority - can be one of urgent, high, normal, low or ad hoc
scheduled	Optional	The date and time when this notification should be displayed
sound	Optional	The sound to play
text	Optional*	The notification body text
title	Optional*	The notification title

Notes

• One of title, text or icon must be provided.
• If the application was registered using a password, the same password must be included. Use of passwords is highly recommended, see the (security) section for more information.

• Using the default event is not recommended - see the (developer guidelines) for more details

Example

{
    "title":"Hello, world!",
    "text":"Just a test...",
    "icon":"!misc-chair",
    "data-misc":"hello word",
    "data-number":"42",
    "callback-invoked":"http-post:http://localhost:8080/callback"
}

GET /notifications/{guid}

Returns information about a previously created notification

Required Arguments

Name	Description
a	A.

Optional Arguments

None.

Response

N.

Possible reasons for failure include:

• N

Example

x

{
  "success": {
    "app-id": "my app"
  }
}

DELETE /notifications/{guid}

Removes a notification from the screen

Required Arguments

Name	Description
a	A.

Optional Arguments

None.

Response

N.

Possible reasons for failure include:

• N

Example

x

{
  "success": {
    "app-id": "my app"
  }
}

---

/info

This endpoint provides information about Snarl itself.

GET /info/version

Returns Snarl version information.

Required Arguments

None.

Optional Arguments

None.

Response

So long as Snarl is running, the following will be returned:

Name	Type	Description
api_version	Integer	The (API version) of Snarl
beta_release	String	Details of the beta release of Snarl, or "" if a general release version is running
release_number	String	The release of Snarl as a string
snp_http_version	String	The maximum version of SNP/HTTP supported by the running instance of Snarl

Example

curl http://host:4444/v2/info/version?access_token=00000001

{
  "success": {
    "release_number": "5.0",
    "beta_release": "Beta 2",
    "api_version": 47,
    "snp_http_version": "2.1"
  }
}