Snarl Network Protocol
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.
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
POST
requests require a request body that is formatted as JSON. All responses (except when calling the root endpoint) are formatted as JSON.
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
All POST
requests must set Content-Type
to application/json
. Other than that, no specific headers are required.
GET
requests are used to return information
POST
requests create new things like application registrations, events and notifications
DELETE
requests unregister applications, remove events and hide notifications
Every request generates the same response. The response will contain two objects:
meta
- which indicates whether the request was successful or not. If the request was not successful, the meta object may contain an explanation of why it failed
data
- contains information relevant to the request. If the request was not successful, an empty data object will be returned
{
"meta": {
"code": 201,
"text": "Created"
},
"data": {
"id": "a7fdb4de-e462-4866-89ce-7b4d28929255"
}
{
"meta": {
"code": 404,
"text": "NotFound",
"reason": "Application 'foo.bar' isn't registered."
},
"data": {}
}
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 |
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 |