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.

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

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": ""
  }
}