Cloud Service External REST API

The Cloud Service External REST API is a RESTful API for interacting with Imaginary Home-based cloud services. Any cloud service supporting the Imaginary Home model will minimally allow any authorized client to interact with it using the API calls specified here.

Overview

This API uses standard HTTP methods (GET, HEAD, DELETE, PUT, and POST) to interact with resources within the cloud service. The cloud service will respond with standard HTTP codes and an optional JSON body (if no body, then the HTTP status code should be NO_CONTENT). Any body sent via PUT or POST should also be submitted as a JSON body.

Authentication

Authentication with the cloud service is done through signed API requests using API keys assigned by the cloud service.

Key signing

The formula using the API access key to generate the Imaginary Home signature is: BASE64(SHA256(LOWER_CASE_METHOD:LOWER_CASE_PATH:API_KEY_ID:TIMESTAMP:VERSION))

For example, let’s assume we have the following scenario:

• Access Key = 123456789
• Secret Key = abcdefghi
• Method = GET
• Path = /location
• Timestamp = 1285971821959
• Version = 2013-01

Then your string to sign would be: get:/location:123456789:1285971821959:2013-01

Headers

Once you have created your signature, you then insert the Imaginary Home headers:

• x-imaginary-signature = the authentication signature generated above
• x-imaginary-version = the version of the API (same as the version in the signature string)
• x-imaginary-timestamp = the timestamp in milliseconds when you generated the request (same as timestamp in signature string)
• x-imaginary-api-key = the access (public) part of your API key (same as the API key ID in the signature string)

Application Pairing

API keys provide strong authentication that may be revoked on an individual basis so that a user may disable a single application at a time. Unfortunately, they are very difficult for most users to understand. The API thus supports an application pairing routine that enables a third-party web site/application to accept a user's user name and password and generate an application specific API key. While OAuth provides a similar mechanism that has a slight security advantage, I have a significant hatred of OAuth and instead opted for something simpler to implement.

NOTE: applications should never, ever store the user's user name and password

The first step is for the application to be paired to submit a POST request to /apiKey with the email and pairing password of the user (the pairing password is a special password the user sets just for pairing operations):

{ "email" : "user@example.com", "pairingCode" : "abc123", "application" : "MyAppName" }

If the email and pairing password match, the cloud service responds with:

{ "apiKeyId" : "1234567890", "apiKeySecret" : "ABCDEFGHIJ1234567890" }

The application should then permanently store the API key ID and secret for use with this API.

Error Handling

The API communicates errors to a client using standard HTTP status codes with a JSON payload describing the error. The JSON includes the following fields:

• status = same as the HTTP status code
• message = a more specific, string error code
• description = a detailed description of what caused the error

Example:

{ "status" : 400, "message" : "InvalidJSON", "description" : "You failed to include an ID in your JSON" }

API Calls

This section describes all of the different API calls in full detail. This section is under development right now.

device

A device that can be managed through this API. Devices of the same type can optionally be organized into fixtures so you can control them together.

fixture

A fixture is a group of devices that should all function together (for a 3-bulb lamp in which the three bulbs are independently controlled as devices).

location

A location represents a physical location such as a home or an office controlled by one or more relays. The location governs all of the devices in that location. A location has at least one user who can manage the devices in that location. A location also has at least one zone.

relay

A relay is an individual relay within a location that controls devices that may span any number of zones within the location.

room

A room is an area with in a zone within a location that contains zero or more fixtures and/or devices.

user

A user is any user of the system. A user may have the right to manage any number of locations.

zone

Each location has at least one zone, but it may be divided into multiple zones. Zones enable a user to define different profiles and schedules for each zone independent of the others. A zone has at least one room.