SNP/HTTP

Introduction

SNP/HTTP allows for quick and easy access to the Snarl API via standard HTTP requests.  Many requests can be run directly from a browser, making SNP/HTTP very easy to learn and troubleshoot.  It’s also platform-agnostic: so long as you can send an HTTP request, you can access Snarl.

Background

There are three varieties of SNP/HTTP:

V0

The original version of SNP/HTTP, now considered deprecated.

V1

A hybrid implementation of SNP/HTTP that uses the same request format as V0, but returns responses using the V2 format.  This is the preferred version to use if you already have an application using the V0 variant.

V2

A forthcoming RESTFul implementation of SNP/HTTP that uses JSON for both requests and responses.  This is the preferred version to use if you’re looking to develop Snarl support for your application.  See the V2 API and Developer Guide for more details.

SNP/HTTP V0

This is the original version of SNP/HTTP that was included with Snarl 2.1.  It is a very easy to use protocol and is ideally suited to smaller applications, especially those which only need to create occasional notifications.

V0 is now considered deprecated – being replaced in Snarl 5.0 with SNP/HTTP V1 – and we encourage anyone using V0 to at least move to V1, and to consider moving to V2.

Request Format

All SNP/HTTP V0 requests must use the HTTP GET method.  An SNP/HTTP V0 request is formatted as follows:

/<command>[?args]

The <command>[?args] query is identical to the standard V42 Snarl API query.

As of Snarl 5.0, the SNP/HTTP V0 implementation returns a human-readable welcome page in response to an empty (that is, ‘/’) request.

Response Format

All SNP/HTTP V0 responses follow the same pattern:

SNP/<version>/<result_code>/<result_text>[/<extra_data>]

Examples:

A successful notify request could return:

SNP/2.1/0/OK/999

This indicates the command was successful and returned token number 999.

A failed request could return:

SNP/2.1/102/UnknownCommand

SNP/HTTP V1

SNP/HTTP V1 is a revised implementation of V0 which returns a V2-styled JSON responses, but uses the same request format as V0.  This should make migration from V0 to V1 incredibly straightforward for most applications.  Only those applications which process the response will need some modification.

Request Format

The request format of SNP/HTTP V1 is identical to that of V0.

To modify your application to use SNP/HTTP V1, rather than using an endpoint of ‘/’, use the endpoint ‘/v1/’.  For example:

V0 request:

/notify?title=Hello%20World%21&text=This%20is%20a%20test

Equivalent V1 request:

/v1/notify?title=Hello%20World%21&text=This%20is%20a%20test

Response Format

SNP/HTTP v1 returns responses formatted as JSON.  Two different types of response can be returned:

Success

A successful request returns a single “success” object containing the following parameters:

  • id: a request-specific identification number, or zero if none exists.

Example

{
  "success": {
    "id": 528
  }
}

Failure

A failed request returns a single “failed” object containing the following parameters:

  • error_number: the error code as an integer
  • error_text: the error as human-readable text
  • hint: further explanation of what went wrong

Example

{
  "failed": {
    "error_number": 102,
    "error_text": "UnknownCommand",
    "hint": ""
  }
}

SNP/HTTP V2

SNP/HTTP v2 is a completely revised version of SNP/HTTP that follows a RESTful approach and uses a more structured request and response format.  At this time, V2 is only a proposed specification.

General

  • Follows the RESTful methodology
  • Defines a small number of endpoints
  • Uses JSON for both requests and responses
  • POST methods must use ‘application/json’ as the content type

Base URI

The base URI is:

/v2/

Endpoints

/apps

Manages application registrations.

/events

Manages application event creations and deletions.

/notifications

Manages notifications.

/info

Returns information about the running instance of Snarl.

Apps Endpoint

POST /apps – register an application

GET /apps/guid – returns information about a previously registered application

DELETE /apps/guid – unregisters an application

 

Events Endpoint

POST /events – adds an event

DELETE /events/guid – removes an event

 

 

Notifications Endpoint

POST /notifications

Creates a new notification.

 

Example

 

{
    "title":"Hello, world!",
    "text":"Just a test...",
    "icon":"!misc-chair",
    "data-misc":"hello word",
    "data-number":"42",
    "callback":"http-post:http://localhost:8080/callback"
}

 

 

 

GET /notifications/guid

Returns information about a previously created notification

 

DELETE /notifications/guid

Removes a notification from the screen

 

Info Endpoint

GET /info/version

Returns Snarl version information:

{
  "version": {
    "release_number": "5.0",
    "beta_release": "Beta 2",
    "api_version": 47,
    "snp_http_version": "2.1"
  }
}

 

Response Structure

The intention is to maintain the same response structure for both SNP/HTTP V1 and V2.  The V1 response structure is documented above, but is also included here for completeness:

Success

A successful request returns a single “success” object containing the following parameters:

  • id: a request-specific identification number, or zero if none exists.

Example

{
  "success": {
    "id": 528
  }
}

Failure

A failed request returns a single “failed” object containing the following parameters:

  • error_number: the error code as an integer
  • error_text: the error as human-readable text
  • hint: further explanation of what went wrong

Example

{
  "failed": {
    "error_number": 102,
    "error_text": "UnknownCommand",
    "hint": ""
  }
}