snarl_network_protocol

Snarl Network Protocol

View the Project on GitHub

Warning 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.

  1. Overview
  2. Objects
  3. Endpoints

Overview

Base URI

The base URI for SNP/HTTP V2 is /v2. So, if Snarl is running on host ninja, and it’s listening for SNP/HTTP on port 4444, an example call would be:

http://ninja:4444/v2/authorise

Content

POST requests require a request body that is formatted as JSON. All responses (except when calling the root endpoint) are formatted as JSON.

Arguments

With the exception of /authorise, every request must include an access_token as an argument within the URL query. For example:

GET http://ninja:4444/v2/notifications?access_token=00000001

Headers

All POST requests must set Content-Type to application/json. Other than that, no specific headers are required.

Methods

Responses

Every request generates the same response. The response will contain two objects:

Example Success Response

{
  "meta": {
    "code": 201,
    "text": "Created"
  },
  "data": {
    "id": "a7fdb4de-e462-4866-89ce-7b4d28929255"
  }

Example Failure Response

{
  "meta": {
    "code": 404,
    "text": "NotFound",
    "reason": "Application 'foo.bar' isn't registered."
  },
  "data": {}
}

Objects

Object Description
application Describes a particular application registration
applications Contains an array of application objects
data Response data object
event Describes a single event class
events Contains an array of event objects
meta Response metadata
notification Describes a particular notification
notifications Contains a list of notification objects

Endpoints

The following endpoints are currently defined:

Endpoint Description
/apps Manages application registrations
/events Manages application event creations and deletions
/notifications Manages notifications
/info Returns information about the running instance of Snarl