Snarl Network Protocol
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.
None
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). |
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:
access_token
title
or app-id
parameters were missing or invalidcurl 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.
Name | Description |
---|---|
app-id |
The application identifier for the registration to delete. |
None.
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:
access_token
app-id
parameter was missing or invalidcurl -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
.
None.
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:
GET
/apps/{app-id}
Returns information about a previously registered application
curl http://ninja:4444/v2/apps/myapp?access_token=00000001
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:
/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.
If authentication was successful, you’ll get a success
object returned with the access_token
included.
{
"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.
Name | Status | Description |
---|---|---|
:appId |
Required | Application identifier. |
Name | Status | Description |
---|---|---|
events |
Required | A completed events object containing the event classes to add or update. |
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.
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
.
Name | Description |
---|---|
app-id |
The application identifier to retrieve information on. |
None.
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:
access_token
.x
{
"success": {
"app-id": "my app"
}
}
DELETE
/events/{app-id}/{event-id}
Removes the event with {event-id}
from registration {app-id}
.
Name | Description |
---|---|
app-id |
The application identifier to retrieve information on. |
event-id |
The event identifier to retrieve information on. |
None.
N.
Possible reasons for failure include:
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.
Name | Status | Description |
---|---|---|
:appId |
Optional | Application identifier. |
:eventId |
Optional | Event identifier. |
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 |
title
, text
or icon
must be provided.Using the default event is not recommended - see the (developer guidelines) for more details |
{
"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
Name | Description |
---|---|
a |
A. |
None.
N.
Possible reasons for failure include:
x
{
"success": {
"app-id": "my app"
}
}
DELETE
/notifications/{guid}
Removes a notification from the screen
Name | Description |
---|---|
a |
A. |
None.
N.
Possible reasons for failure include:
x
{
"success": {
"app-id": "my app"
}
}
/info
This endpoint provides information about Snarl itself.
GET
/info/version
Returns Snarl version information.
None.
None.
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 |
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"
}
}