Getting Started with WebSNP
WebSNP (previously known as SNP/HTTP) allows client applications to create Snarl notifications using simple HTTP GET requests. The client can be running on the same server as Snarl, on different machines on the same network, or even on different machines connected via the Internet.
This tutorial will work through the basics of creating notifications using WebSNP.
Firstly you must be running Snarl 5.0 or later, and you must have a Receiver (Listener) configured for incoming WebSNP requests. This tutorial explains how to do the latter.
We will use curl for this tutorial. Curl might already be installed on your computer, but if not, you can download it here.
First off, let's make sure everything is set up correctly. Enter the following into a Command Prompt or Terminal window:
curl "http://localhost:8084/v1/"This assumes that Snarl is running on the same computer you're using for this tutorial, and the the Receiver you configured is set to use port 8084. If either of these are different, you can substitute the correct value accordingly.
If everything is set up correctly, you should get the following back:
<html><body><h2>Welcome to WebSNP!</h2><p>You can access the classic API here, or the more advanced V1 and V2 APIs by using the <code>v1</code> and <code>v2</code> prefixes respectively, and you can find more about WebSNP <a href='http://snarl.fullphat.net/content/developers/snarl-network-protocol-snp/snphttp/'>here</a>.</p><p>Seeing as you're here, why not <a href='/v0/notify?title=Hello, word!&text=WebSNP test'>try out a simple notification</a>?</p></body></html>What actually appears may look slightly different depending on the version of Snarl you are using.
Next, let's have Snarl display a notification.
Enter the following:
curl "http://localhost:8084/v1/notify?title=WebSNP Test&text=Just a test...&icon=!misc-alien"With luck you should see the following returned in the console:
{
"Meta": {
"Success": true,
"Code": 252,
"Text": "Created",
"Message": "",
"Host": "GANYMEDE",
"Server": "Snarl 5.1.0"
},
"Content": {
"Value": 460
}
}And the following appear on the machine running Snarl:
There's quite a bit going on here, so let's break it down:
-
v1/signifies that you're wanting to use the Version 1 API, which is the second - and current - iteration of WebSNP; -
notifyindicates that you're wanting to display a notification; -
title=WebSNP Test&text=Just a test...&icon=!misc-aliendefines the content to be used in the notification.
You will also notice that the request follows a traditional URI structure:
- Path:
/v1/notify - Query:
title=WebSNP Test&text=Just a test...&icon=!misc-alien
From a RESTful perspective, /notify could be considered as the endpoint.
It's possible that this tutorial has given you enough information to progress with WebSNP, however creating notifications is just the tip of the iceberg in terms of what WebSNP can do.
WebSNP also supports registering your application with Snarl, creating different event classes for different types of notification, and - starting with Snarl 5.1 - also includes the ability to sign and encrypt requests.
To find out more, take a look at the WebSNP Guide, and the WebSNP Reference pages.
So far we've created anonymous notifications. These are notifications sent directly to Snarl, but without an owning application. If you move the mouse pointer over the notification, you can see that Snarl displayed the notification, but isn't too happy about it...
While this is okay for testing and demonstration purposes, applications should register themselves with Snarl and then create notifications using their own registration. Anonymous notifications may be blocked by the end user or system administrator, and registering with Snarl gives you (and the end user) more control over any notifications you create.