Relay API v1.0 is now live
Today we’re pleased to announce version 1.0 of the Relay API, which enables you to post messages to registered Relay devices programmatically. Using the API you can for example hook up temperature and humidity sensors to your Relays to display the values they’re reporting, assuming those sensors are capable of making HTTP requests to the API.
To use the API, you first need to get an API key for the device you’d like to post to. The device must be registered to your account. Login to your account and navigate to the “Get API Key” option in the left hand sidebar. You should see a list of API keys for each of your registered Relay devices, as well as the device ID for each of those devices.
To make a call to the API, you will require the device ID and API key, besides the message you’d like to post. Calls should be made in the format below:
https://relay.foundrytechnologies.com/messages/api_create/<device ID>/<API key>/<message text>
The message text should be URL encoded. To learn more about URL encoding, you can check online resources such as this one.
Once messages are successfully submitted to the target Relay, it will update within 5 minutes or less as usual to reflect the new message. Successful requests will return a 200 status code. Failed requests (bad or missing device IDs, API keys, and messages) will return a 400 code. A descriptive message is returned in JSON. Here are a few sample JSON responses:
Successful message submission (returns a unique ID for the submitted message):
{"status":200,"description":"37"}
Bad device ID:
{"status":400,"description":"No such device."}
Missing message:
{"status":400,"description":"No message specified."}
As always for Relays, messages take precedence over images. If the target Relay was previously displaying a message, the message text will be displayed instead at the next refresh. If it was displaying a message, that message will be changed to reflect the new one posted via the API.
So there you have it. We’re excited to see what projects the community will develop using the new API. If you come up with any interesting applications, please do write in or tweet to us and let us know about them.
Of course we plan on adding more to the API as time goes on – functionality such as posting images besides text is on our radar screen.
