spate documentation

Spate DocumentationRelease 0.1

Joe Alcorn

November 18, 2014

Contents

1 API 31.1 API version 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Javascript Client Library 52.1 Basic Usage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 What is spate? 7

4 Your first application 9

5 Libraries 11

6 Support 13

HTTP Routing Table 15

i

ii

Spate Documentation, Release 0.1

Contents:

Contents 1

Spate Documentation, Release 0.1

2 Contents

CHAPTER 1

API

1.1 API version 1

Version 1 of the API is still in development and subject to changes.

Note: You’ll only need to read this documentation if you’re interacting with the API personally. If you’re using alibrary you should refer to its own documentation. See Libraries.

1.1.1 Authentication

Authenticating the push endpoint is simple once you know how.

You take the application’s secret key and compute a hmac-sha256 signature of the payload’s message. If you’ve neverdone that before, don’t worry, it sounds more complicated than it is. Chances are there is a library to do it for you inyour language of choice, if it’s not already in the standard library!

Here’s an example of what I mean:

>>> from hashlib import sha256>>> import hmac>>> secret = ’ssshh’>>> message = ’Hello World!’>>> signature = hmac.new(secret, message, sha256).hexdigest()>>> print signature8650decb780ea45364e7a6f9f8cbb3c87f75777910366359ae0c4aeca1db763a

1.1.2 Endpoints

All API requests are made over HTTPS, to a base URL of https://api.gorealti.me

Data must be sent as JSON, with a Content-Type: application/json header.

Push

POST /v1/push

Status Codes

• 202 – Ok

3

Spate Documentation, Release 0.1

• 400 – Request data incorrect or missing

• 401 – Invalid signature

Request data

Json Parameters

• app (string) – app key

• message (string) – data to push to client

• signature (string) – signature created with app secret, see Authentication

• channels (list) – list of channels to push message to

Response

HTTP/1.1 202 OKVary: AcceptContent-Type: application/json

{"accepted": true

}

4 Chapter 1. API

CHAPTER 2

Javascript Client Library

2.1 Basic Usage Example

var client = new Spate(’<APP_KEY>’)client.on(’my_channel’, function(data) {

alert(data.message);});

class Spate(app_key, verbose)

Arguments

• app_key (string) – Your application key (not secret!)

• verbose (boolean) – Log messages to console if true (default false)

on(channel, callback)Calls callback with message data when a message is pushed down channel. Subscription to thatchannel will be added if it doesn’t already exist.

See Callbacks

Arguments

• channel (string) – The name of a channel

• callback (function) – Function to call with message data

off(channel)Removes callback and unsubscribes from channel

Arguments

• channel (string) – The name of a subscribed channel

2.2 Callbacks

Callbacks should accept one param, which will be an object structured like so.

{"type": "message","channel": "my_chan","message": "Hello World!",

5

Spate Documentation, Release 0.1

"received": 1399841133,}

6 Chapter 2. Javascript Client Library

CHAPTER 3

What is spate?

At it’s core, spate is a service that aims to simplify the use of realtime technologies in your applications.

By removing the need to manage servers, write tons of boilerplate code and then maintain both of these, spate is theeasiest way to integrate realtime tech available.

By consuming our simple HTTP-based API and making use of a javascript library you’re able to get up and runningwith under 10 lines of code!

7

Spate Documentation, Release 0.1

8 Chapter 3. What is spate?

CHAPTER 4

Your first application

Before you’re able to do anything on spate you must create an application. This is a straightforward process so thisguide won’t cover it in detail.

First you’ll need to register a user account here. Once that’s done you’re able to create an application on the newapplication page.

After creating your application you’ll be taken to the application dashboard. There’s not much you can do there atpresent, but that’ll change shortly. For now all we need is the application key & secret anyway.

Warning: Your application secret must absolutely always remain secret. Compromised secrets can be regeneratedon the application dashboard.

9

Spate Documentation, Release 0.1

10 Chapter 4. Your first application

CHAPTER 5

Libraries

Some recommended libraries are listed below for each language. Don’t see a library for a language you use? Why notwrite one? Our API is super simple to use!

• Python (docs)

If you’re unable to find a library that takes your fancy why not write one using the API documentation

11

Spate Documentation, Release 0.1

12 Chapter 5. Libraries

CHAPTER 6

Support

If you are unable to find what you’re looking for in these docs please email support@spate.io.

13

Spate Documentation, Release 0.1

14 Chapter 6. Support

HTTP Routing Table

/v1POST /v1/push, 3

15

Spate Documentation, Release 0.1

16 HTTP Routing Table

Index

Ooff() (built-in function), 5on() (built-in function), 5

SSpate() (class), 5

17