Spark

Introduction

The Spark API is currently in rapid development—things are changing fast! Responses are currently dummy data.

  • HTTP GET requests retrieve data from a device without changing its state.
  • HTTP POST requests send data to a device, usually changing its state in the process.

If you already know the other common HTTP verbs, then you know what they do, if not, don't worry, you'll understand in a minute—just keep reading.

Endpoints

All Spark API URLs start with

https://api.sprk.io/v1

So that means:

  • you always have to use TLS—https: not http:
  • and the domain name is api.sprk.io.

Response Format

Server responses are in JSON and always contain the key "ok". The value of the "ok" key is boolean: true or false.

{ "ok": true }

If ok is false, there will also be an "errors" key. The value of "errors" is an array of error messages.

{
  "ok": false,
  "errors": [
    "Bad pin: lambswool",
    "Bad value: palm tree"
  ]
}

You may send request data either web form encoded or in JSON. With curl's -d flag, the default encoding is application/x-www-form-urlencoded, but some data structures are hard to represent that way.

If you are sending arrays or deeply nested structures and get frustrated with web form encoding (or if, like us, you prefer the robustness and clarity of JSON) just set the Content-Type header for your request to application/json.

# web form encoded, short & sweet
curl https://api.sprk.io/v1/devices/elroy -d message=winning

# same thing, but sending JSON
curl https://api.sprk.io/v1/devices/elroy \
     -d '{"message":"winning"}'           \
     -H 'Content-Type: application/json'

Authentication

Right now there is no need to authenticate. Play with our dummy data unburdened by your weighty indentity!

Control a Device

Set Pins High/Low

POST /v1/devices/:id (pin, level)

The simplest thing you can do with a Spark Core is to set one of the exposed pins high or low. This is like digitalWrite() in Arduino or Wiring (the framework Arduino was built on).

There are 16 GPIO pins exposed on a Spark Core, 8 digital (D0–D7) and 8 analog (A0–A7). This call may be performed on any of these 16 pins. The level argument must be either HIGH or LOW.

curl https://api.sprk.io/v1/devices/elroy -d pin=D0 -d level=HIGH

Custom Messages

POST /v1/devices/:id (message)

Often you need to do something a bit more complex than just setting a pin high or low. That's when you should write your own Arduino-compatible embedded code.

If you implement a function called userFunction() in your embedded code, you can trigger it from the API by including the "message" key in your POST data. The value of the "message" key will be passed as the string argument to your function.

Keep messages short. The server will reject them if they're much longer than a tweet.

The syntax for custom messages will change slightly to be even easier very soon!

curl https://api.sprk.io/v1/devices/elroy \
     -d "message=set_color #1180FF"

Receive Data From a Device

But what about pushing data out from the device? For many situations, the electronics will sense something that triggers a message to the outside world.

Server-Sent Events (SSEs)

GET /v1/devices/:id/events

Open a stream of server-sent events. The event names and their data will be defined by the particular device you're interacting with.

Imagine a connected toy. We'll call it: box. This toy has sensors, like an accelerometer, so it knows which side is facing up. The sides are labeled 1, 2, 3, 4, 5, 6.

When writing an awesome app to allow parents to interact with kids from a distance while the kids are playing with the box, the parents want to know which side is up at all times.

Dad opens his box app, which makes this API call to open an event stream. The connection is kept alive and the app UI updates immediately anytime the box changes orientation.

curl https://api.sprk.io/v1/devices/elroy_box/events

Here's what the event stream received by the app might look like. The app should ignore those extra colons. They're comments, just used as keep-alive signals.

event: orientation
data: 6

:
:
event: orientation
data: 1

:
event: orientation
data: 2

Callbacks to Your Server

Another way to access device data/events is for the Core to trigger an HTTP callback. Example time.

You own a pizza shop. Your customers want a big, red button they can just smack to automatically order a pizza for delivery. So, you add a POST /order route to your website, and you register it as a callback that your Spark-powered pizza button can trigger.

Now, in the pizza button embedded code you write userCallback("pizza"); to run when the button is smacked, which tells the Spark servers to perform the pizza callback!

This documentation's making me hungry.

# on the device...
userCallback("pizza");

# Spark server whispers to crazyawesomepizza.com server...
POST /order HTTP/1.1
Host: crazyawesomepizza.com

Groups

Every example above is for a single device, but all the same calls apply to groups. You create, read, update, and delete (CRUD) groups in the standard RESTful way with the HTTP verbs POST, GET, PUT, and DELETE.

Create a group of two devices. Remember, by using curl's -d flag, you're automatically sending a POST request, though if you want to include -X POST it works fine.

curl https://api.sprk.io/v1/groups       \
     -H 'Content-Type: application/json' \
     -d '{
           "name"    : "the_boyz",
           "devices" : ["elroy", "george"]
         }'

List the devices in a group.

curl https://api.sprk.io/v1/groups/the_boyz

Change which devices are in a group.

curl https://api.sprk.io/v1/groups/the_boyz \
     -H 'Content-Type: application/json'    \
     -X PUT                                 \
     -d '{ "devices": ["elroy", "george", "astro"] }'

Delete a group.

curl https://api.sprk.io/v1/groups/the_boyz -X DELETE