This is provisional documentation. Applications should not attempt to implement any features listed in this document, other than for development or testing purposes. The documentation is provided for open access to encourage interest in forthcoming features and to solicit feedback and suggestions. It is therefore provided "as is" and is subject to ongoing change and revision.

Registering and Unregistering

Registering

Applications are registered by POSTing a registration object to Snarl. The registration object looks like this:

{
  "app-id": "foo.bar", 
  "title": "Foo.Bar"
}

Let's say we want to register application foo.bar with Snarl:

curl -H "Content-Type: application/json" "http://192.168.1.1:8080/v2/apps" -d "{ \"app-id\": \"foo.bar\", \"title\": \"Foo.Bar\" }"

Returns:

{
   "meta": {
    "code": 201,
    "text": "Created"
  },
"data": {
    "app-id": "foo.bar",
    "title": "Foo.Bar",
    "type": "Application",
    "first_registered": "Sun, 11 Mar 2018 19:05:21 GMT",
    "last_registered": "Sun, 11 Mar 2018 19:05:21 GMT",
    "is_authorised": true,
    "is_secured": false,
    "icon": "C:\\Users\\foo\\AppData\\Local\\Temp\\b5753472-8fb7-42c4-949d-df80ef025bfd.png"
  }
}

Indicating that the application was successfully registered. Note that the data object in the response contains the corresponding application object for the registered application.

Snarl R5.0 only needs an application to be registered once rather than each time Snarl is launched.

Unregistering

Applications unregister by calling the DELETE /v2/apps/ endpoint, passing both the private identifier and the password used when it was first registered. Usually, an application would only unregister as part of its uninstallation process.

Typically, applications should not need to unregister themselves with Snarl. Unregistering with Snarl causes any customisation the user has created to be lost, and will require your application to re-register with Snarl.

Events

Creating an Event

Deleting an Event

Displaying a notification

We saw above how to create a simple notification using the built-in Grampf application to handle it. Normally however, you'll register an application, create events, and then generate notifications against that application and one of the events you've added.

This is done by POSTing to the /v2/notifications/ endpoint, passing the application identifier and event identifier to use in the URI, and details about the notification itself in the request body.

Examples

Let's say we have an application registered as app with an event called foo. We can create a simple notification as follows:

curl -H "Content-Type: application/json" "http://cs30:8080/v2/notifications/app/foo" -d '{ "title": "Hello, world!" }'

{
  "success": {
    "id": "dc506c1b-bab8-4bdc-b8bb-ebf91a53366c"
  }

And the same notification, but using an icon that's stored on the machine displaying the notification:

curl -H "Content-Type: application/json" "http://server:8080/v2/notifications/app/foo" -d '{ "title": "Hello, world!", "icon": "c:/icons/home.png" }'

Objects

Object	Description
application	Describes a particular application registration
applications	Contains an array of application objects
data	Response data object
event	Describes a single event class
events	Contains an array of event objects
meta	Response metadata
notification	Describes a particular notification
notifications	Contains a list of notification objects

Endpoints

The following endpoints are currently defined:

Endpoint	Description
/apps	Manages application registrations
/events	Manages application event creations and deletions
/notifications	Manages notifications
/info	Returns information about the running instance of Snarl