All API calls take the form of HTTP requests, using the four basic verbs: GET, POST, PUT, and DELETE.
The format [:x] represents a parameter, where :x will be passed on as an argument.
Responses will come in the form of HTTP status codes (e.g. 200 OK), JSON data, or both.
Wrappers will be developed for common languages such as Ruby, Java, Python, Javascript, and Objective-C, but they are not yet available.
This API is still in its early days, so expect lots and lots of changes.
Possible HTML status codes are as follows:
- 200 OK: You're good.
- 400 Bad Request: Your syntax wasn't right.
- 401 Unauthorized: You didn't give us your API key, and you tried to access a protected device.
- 403 Forbidden: Your API key is not authorized to access this device.
- 404 Not Found: These are not the droids you're looking for. No device by that name.
- 405 Method Not Allowed: Seems like you might have used the wrong HTTP method. Oops.
- 409 Conflict: Used for scheduled commands. Someone has already scheduled a command at that time.
- 418 Teapot: I'm a teapot.
- 429 Too Many Requests: Slow down!
- 460 Incapable: That device cannot run that command. Try checking the devicetype.
- 461 Action Forbidden: You may be authorized to access the device, but you're not authorized to make that command.
- 500 Internal Server Error: Fail.
- 503 Service Unavailable: Fail. Overloaded or down for maintenence.
Other error messages might be produced automatically by Node.js/Express, but these are the ones that we implemented ourselves.
Returns the status of the device as JSON.
GET http://sprk.io/device/[:deviceid]/status
Example: GET http://sprk.io/device/Elroy/status
Example response: { "deviceid" : "Elroy", "devicetype" : "Light" "devicestatus" : 0, "dimval" : 255 }
For debugging purposes. Returns the local logs from the device. Format of the response has not yet been developed.
GET http://sprk.io/device/[:deviceid]/logs
Turns the light on. Returns a status code (OK, error).
PUT http://sprk.io/device/[:deviceid]/turnOn
Turns the light off. Returns a status code (OK, error).
PUT http://sprk.io/device/[:deviceid]/turnOff
Toggles the status of the light. In other words, if the light is on, it turns off, and if it's off, it turns on. Returns a status code (OK, error).
PUT http://sprk.io/device/[:deviceid]/toggle
Fades the light to a certain dim level over the specified duration. The target dim level should be an intger from 0 to 12. Other numbers or non-numbers will return an error. The optional duration is in milliseconds from 0 to 600000 (ten minutes), and it defaults to 400 if a bad value is provided or if omitted.
PUT http://sprk.io/device/[:deviceid]/fade/[:target]/[:duration]
PUT http://sprk.io/device/[:deviceid]/fade/[:target]
Dims the light to a certain dim level. Dim level should be an integer from 0 to 255; other numbers or non-numbers will return an error. If the light is off, the dim function will not turn it on; rather, it will set the dim level that the light should turn to the next time it is turned on.
PUT http://sprk.io/device/[:deviceid]/dim/[:dimval]
Pulses the light; if light is off or at a low dim level, the light will pulse on. If light is on at a high dim level, the light will pulse off.
PUT http://sprk.io/device/[:deviceid]/pulse
Schedules an action at a later date. Any of the above actions can be used. Uses ISO 8601 time format (http://en.wikipedia.org/wiki/ISO_8601). Returns a status code (OK, error). Will return an error if another action has been scheduled for the same time.
POST http://sprk.io/device/[:deviceid]/schedule/[:action]/[:YYYYMMDDThhmmss+-hhmm]
Example: http://sprk.io/device/Elroy/schedule/turnOn/20120809T180000-0500 The above example would turn on the light Elroy on August 9, 2012 at 6pm ET (-500)
Gets a list of scheduled actions for the device. Returns the list in JSON format. The key for each scheduled action is a unique 12-byte value, generated by MongoDB. See http://www.mongodb.org/display/DOCS/Object+IDs for info on ID formatting.
GET http://sprk.io/device/[:deviceid]/schedule
{ "deviceid" : "Elroy", "schedule" : { "4c2209f9f3924d31102bd84a" : { "time" : "20120809T180000-0500" "action" : "turnOn" } "4c2209f9f3924d31102bd84b" : { "time" :"20120809T210000-0500" "action" : "turnOff" } } }
Deletes a scheduled action using its unique ID.
DELETE http://sprk.io/device/[:deviceid]/schedule/[:scheduleid]
Gets a list of the last 20 actions taken by the device. Returns the list in JSON format. As with schedules, each action has a unique 12-byte ID as its key, generated by MngoDB. Uses ISO 8601 time format (http://en.wikipedia.org/wiki/ISO_8601).
GET http://sprk.io/device/[:deviceid]/history
{ "deviceid" : "Elroy", "history" : { "4c2209f9f3924d31102bd84a" : { "time" : "20120809T180000-0500", "action" : "turnOn", "devicestatus" : 1, "dimval" : 255 } "4c2209f9f3924d31102bd84b" : { "time" : "20120809T180000-0500", "action" : "turnOn", "devicestatus" : 1, "dimval" : 255 }, "4c2209f9f3924d31102bd84c" : { "time" : "20120809T210000-0500", "action" : "turnOff", "devicestatus" : 0, "dimlevel" : 255 } } }
TBD. Haven't decided yet how developers will get access to a user's devices. Stay tuned!