Snarl Network Protocol
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.
Oxide is the new name for our SNP/HTTP API. SNP/HTTP stands for “Snarl Network Protocol over HTTP”, which - apart from being a bit of a mouthful - is also starting to become slightly inaccurate, especially with the latest iteration of this API.
This guide covers Oxide v2, a completely revised version of SNP/HTTP that follows a RESTful approach and uses a more structured request and response format. For earlier versions of SNP/HTTP see (here).
At this time, version 2 is a developing specification. We welcome contributions and suggestions to the specification but we strongly advise against attempting to implement it in anything other than a test application.
Oxide v2 was first introduced in Snarl 5.0 Beta 2.
The response Oxide returns has changed in Snarl 5.0 Beta 6. Now, Oxide will return a standard response irrespective of whether the request succeeded or failed. See Response for more details.
Compared to previous versions of SNP/HTTP, Oxide v2:
Oxide enforces a number of standards in order to ensure a consistent approach. If you’ve worked with other RESTful APIs, these should be no different:
POST
methods create or add artefactsGET
methods retrieve informationDELETE
methods delete or remove artefactsPOST
methods must use application/json
as the content typeoxide-authorisation
will be used to authorise communication with SnarlMost applications will use an existing wrapper library in the language of your choice, but it’s important to familiarise yourself with the underlying API HTTP methods first.
There’s no easier way to get started than by using Curl, so let’s dive straight in and say hello to Snarl:
curl "http://localhost:8080/v2/"
Snarl responds with:
Welcome to the Oxide version 2 API! Note that this API is in development and, as such, should only be used for testing purposes. Find out more about Oxide here: https://github.com/fullphat/snarl_network_protocol/wiki/Oxide-Developer-Guide
The first thing to note is that we’re using Curl to talk to Snarl. Curl comes installed on OS X and most mainstream Linux distributions. If you’re running Windows, you can download it from here. We use Curl in this guide as it’s an excellent way to show the raw request and response content.
We’re talking to Snarl running on localhost
and on port 8080, but we could just as well be talking to it on another server on our network, or even over the Internet. See (here) for how to configure Oxide to listen on a particular port and (here) for how to get Windows to listen on more than just localhost
.
Now we’ve proven that Snarl’s listening, let’s display a notification:
curl -H "Content-Type: application/json" "http://localhost:8080/v2/notifications" -d '{ "title": "Hello, world!" }'
{
"meta": {
"code": 201,
"text": "Created"
},
"data": {
"id": "a7fdb4de-e462-4866-89ce-7b4d28929255"
}
}
There’s a bit going on here, so let’s step through it…
Firstly, we’re talking to the notifications
Oxide endpoint and, because we want to create a notification, we need to POST
the data to Snarl (this is implied using the -d
Curl switch) and we need to set the Content-Type:
header to application/json
. Finally, we pass the following nugget of JSON in the request body to describe the notification we want:
{
'title': 'Hello, world!'
}
Snarl responds with:
{
"meta": {
"code": 201,
"text": "Created"
},
"data": {
"id": "a7fdb4de-e462-4866-89ce-7b4d28929255"
}
}
And the following appears on screen:
This generates probably one of the most simplest notifications you can create, but it shows just how easy it is to talk to Snarl. Let’s really crank things up a notch and change the icon:
curl -H "Content-Type: application/json" "http://localhost:8080/v2/notifications" -d '{ "title": "Hello, world!", "icon": "!misc-hammer" }'
Gives us this back from Snarl:
{
"meta": {
"code": 201,
"text": "Created"
},
"data": {
"id": "2d381ea2-7002-48f5-8d0f-d25543b97a2d"
}
}
And this on screen:
Note that Snarl returns a different id
this time. This is the notification’s unique identifier and, as we just created a new notification, we’ve got a new identifier.
Not currently implemented. However, the hash algorithm, key hash and salt would be passed in the oxide-authorisation
header of each request if the transport is password-protected. This would use the same format as SNP 3.1.
oxide-authorisation: MD5:0000000000000000.123456
Applications are registered by POST
ing an Oxide registration
object to Snarl. 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.
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 POST
ing 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.
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://localhost: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" }'
localhost
By default, Windows 7 and above limits the ability for web servers to only be able to listen for incoming connections on localhost
. To remove this restriction, do the following on the machine running Snarl:
8080
with the port number you’ve configured Snarl to listen for Oxide requests on:netsh http add urlacl url=http://+:8080/ user=Everyone listen=yes