1. Introduction
2. Overview
3. Messages
   i. Requests
   ii. Responses
   iii. Signals
4. Forwarding
5. Subscriptions
6. Security
   i. Authorisation
   ii. Encryption

SNP/HTTP v1 is a revised implementation of v0 which returns a JSON-formatted response, but uses the same request format as v0.  This should make migration from v0 to v1 very straightforward for most applications: only those applications which process the response will need some modification.

A SNP/HTTP conversation is held between a client and a server with the client initiating the request, and the server responding to the request appropriately. The process is as follows:

1. Client opens a connection to the server
2. Client issues a request
3. Server takes action and issues an appropriate response
4. Client either closes the connection or repeats step 2

The client and server may be on the same physical machine, on different machines, or even split across the Internet. If a client wishes to send a request and then close, it must wait until it has received the response from the server, even if it does not plan to do anything with it.

Awaiting allocation - port 8084 requested.

Content values should be encoded as UTF-8.

A SNP/HTTP v1 message is the same as a standard HTTP GET request.

Three message types are defined:

• Request: issued from a client to a server asking the server to do something;
• Response: issued from a server to a client in reply to a request. The response will indicate whether the previous request succeeded or not;

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

SNP/HTTP v1 returns a response formatted as JSON.  An example response looks like this:

{
  "Meta": {
    "Success": false,
    "Code": 102,
    "Text": "UnknownCommand",
    "Message": "",
    "Host": "cs30",
    "Server": "Snarl 5.1.0"
  },
  "Content": null
}

Every response contains two objects: Meta and Content. Meta will always be provided and indicates whether the request succeeded or not; Content will only be provided if the request succeeded, otherwise it will be null.

The Meta object contains information about the response, specifically whether it was successful or not.

if the request was successful, the Content object will contain a single Value integer field which will contain a value relevant to the request. If the request was not successful, Content will be null:

{
  "Meta": {
    "Success": true,
    "Code": 252,
    "Text": "Created",
    "Message": "Notification created",
    "Host": "cs30",
    "Server": "Snarl 5.1.0"
  },
  "Content": {
    "Value": 456
  }
}

Security covers two parts: authorisation and encryption. Authorisation ensures the receiving server trusts incoming messages from a particular client by validating that they both share a common secret (in this case, a password); encryption protects the contents of the message from inspection during it's journey from the client to the server.

Messages can include authorisation without including encryption, however the reverse is not true, as encrypted messages rely on the key created during the authorisation process. So, if you want encryption, you’ll need to also use authorisation.

To authorise a message, the password must be translated into a key hash using a supported hash algorithm and salt (see the Developer Guide for details on how to generate these values). This is all then included in the HTTP request Authorisation: header, as follows:

Authorization: SnarlLock {hashAlgorithm}:{keyHash}.{salt}

GET /v1/notify?title=Hello%20World%21&text=This%20is%20a%20test HTTP/1.1
Authorization: SnarlLock SHA256:EB1452C0F7AEF122588A053386658BB8023C484EE136DA79D8E779D9EC90862B.ACAA8464D48BB97D89380F58243F97B1
Host: 192.168.1.16:4444
Connection: Keep-Alive

Note that authorisation is not the same as authentication. Authentication applies to individual application registrations and ensures that one application cannot spoof notifications from another application.

Encrypting a message requires both authorisation and a valid encryption algorithm and initialisation value. The HTTP request Authorization: header is modified to include the encryption metadata as follows:

Authorization: SnarlLock {hashAlgorithm}:{keyHash}.{salt}-{encryptionAlgorithm}:{iv}

The following is an encrypted SNP/HTTP request:

GET /06F0313F1B2FB7C03A0ECB8F14C71F7CAE4511846302BFABA48170CE15DB16EB8C9AE513B26F1CCACC2FD25D620C0A2DCA7D67EDC5A04FFC4F62DA1F77B7215CD489AA46B09B5217D30CBA297205BEBE HTTP/1.1
Authorization: SnarlLock SHA256:EB1452C0F7AEF122588A053386658BB8023C484EE136DA79D8E779D9EC90862B.ACAA8464D48BB97D89380F58243F97B1-AES:D3531772621C382AA483D43455ABF352
Host: 192.168.1.16:4444
Connection: Keep-Alive

Hex-encoding the message content typically doubles the overall size of a message packet compared to the same packet unencrypted. As notifications are by nature intended to be brief, this should not be a significant issue. However, if a client typically transfers a large amount of meta data along with the notification, consideration should be given to using a different mechanism to transfer the data - especially if network bandwidth is a concern.