Introduction to Oxide Web - fullphat/snarl_network_protocol GitHub Wiki

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/Web allows applications to communicate with Snarl using the Oxide API over HTTP (and its SSL/TLS sibling). Oxide is the latest iteration of the Snarl API, following on from the Hydride API introduced in Snarl V42 (R2.4).

You can read more about the Oxide API here, and you can find information on the Hydride-based HTTP protocol - SNP/HTTP - here.

Like any good API, Oxide/Web enforces a number of standards in order to ensure a consistent approach. If you've worked with other RESTful APIs, these should be very familiar. You can read about the standards in the Proposed Specification.

Oxide/Web is available in Snarl 5.0 Beta 10.

Trying it out

While most applications will likely use an Oxide/Web wrapper library in the language of their choice, if you want to get into the detail of Oxide it's important to familiarise yourself with the underlying API methods first - and there's no easier way to get started than by using Curl. Assuming you've got Snarl up and running and it's listening on port 8080, open a Command Prompt and try the following:

curl "http://localhost:8080/v2/"

Snarl responds with:

Welcome to the Oxide/Web 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 usually comes installed by default on OS X and most mainstream Linux distributions. However, 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.

The next thing to note is that we're talking to Snarl running on localhost:8080, but we could just as well be talking to it on a different server on the local network, or even over the Internet. See (here) for how to configure Oxide/Web to listen on a particular port and here for how to get Windows to listen on more than just localhost.

Next steps

Now we've proven that Snarl is listening, let's display a notification:

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

We should get the following back from Curl:

{
  "Meta": {
    "Code": 901,
    "Text": "Created",
    "Message": "Notification created",
    "Timestamp": "2018-05-19T17:10:46.191792+01:00",
    "Host": "cs30",
    "Platform": "Win32NT",
    "PlatformVersion": "6.1.7601.65536"
  },
  "Data": {
    "Guid": "bca9fa20-5d46-42f6-9f24-48ec260367fd"
  }
}

And the following appears on-screen:

There's a bit going on here, so let's step through it...

Firstly: we're talking to the notifications service, which handles anything to do with notifications. As 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 to comply with Oxide/Web's standards. Finally, we pass the following nugget of JSON in the request body to describe the notification we want:

{
  "title": "Hello, world!"
}

Snarl responds with a bit of JSON back, which indicates the notification was created successfully. We can get more information about it by using the returned Guid, but more on that later.

Ramping up

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" -d "{ 'title': 'Hello, world!', 'icon': '!misc-hammer' }" "http://localhost:8080/v2/notifications"

Gives us this back from Snarl:

{
  "Meta": {
    "Code": 901,
    "Text": "Created",
    "Message": "Notification created",
    "Timestamp": "2018-05-19T17:10:48.191792+01:00",
    "Host": "cs30",
    "Platform": "Win32NT",
    "PlatformVersion": "6.1.7601.65536"
  },
  "Data": {
    "Guid": "2d381ea2-7002-48f5-8d0f-d25543b97a2d"
  }
}

And this on screen:

Note that Snarl returned a different Guid this time. This is the notification's unique identifier and, as we just created a new notification, we've got a new identifier.

Registering

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.