Upload
others
View
18
Download
0
Embed Size (px)
Citation preview
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 [email protected].
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