Controlling RainMachine through REST API

From RainMachine wiki page
Jump to: navigation, search

Controlling RainMachine through REST API

The entire API documentation is available here: http://docs.rainmachine.apiary.io/

The RainMachine provides a REST API to interact directly with your device.
Interacting with our API is possible from every language and platform that supports HTTPS.
For the RainMachine Mini 8 and RainMachine Touch HD the RESTful interface is accessible via HTTPS on port 8080 while for the first generation RainMachine API is accessible via HTTPS port 443. All responses are in JSON format

In the following examples will consider that your RainMachine has the ip address 192.168.12.175. You can replace this ip address with host name, cloud host name or a mock server address from
http://docs.rainmachine.apiary.io/ (eg: https://private-bd9e-rainmachine.apiary-mock.com/)

First API call (getting the basic information about device):
Simply open this url in your browser: https://192.168.12.175:8080/api/apiVer you should receive a json with several key/values:

{
"apiVer": "4.0.0",
"hwVer": 2,
"swVer": "4.0.535"
}

Here apiVer means the version of the API available on device, hwVer is the hardware version of the device and swVer is the rainmachine app version.
Notice that this API call didn’t require any authentification with the device, but except this call and auth/login call all other calls must use a OAuth token otherwise an error 401 Unauthorized will be returned.

Authenticating with the device:
The first step on working with API calls that require authentification is obtaining a OAuth token. Once you have this token you should add it to all your requests like this: https://192.168.12.175:8080/api/4/program?access_token=YOUR_ACCESS_TOKEN.
If you don’t have a token you must login to the device first. This is accomplished by a POST request with /auth/login as URL and with json body containing the password:

curl -X POST -k -d ' { "pwd": "admin", "remember":0}' https://192.168.12.175:8080/api/4/auth/login

The received json will contain:

{
"access_token": "eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab",
"checksum": "a31f3570f9ac79387400e87719df93d1028479c45ed46948abf96800218b0c5146dbcd7ce0e11cc1b671e1f579766334d05caf4c9fe80201",
"expires_in": 86400,
"expiration": "Thu, 04 Jun 2015 10:02:50 GMT",
"statusCode": 0
}

Now you can use the value from “access_token” key to call the rest of the API calls. Using the access token to get the daily statistics: Simply issue a GET request with /dailystats call:

curl -k https://192.168.12.175:8080/api/4/dailystats?access_token=eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab

The received JSON will look similar to:

{
"DailyStats": [
{
"id": 0,
"day": "2015-06-03",
"mint": 22.699999999999999,
"maxt": 28.800000000000001,
"icon": 2,
"percentage": 87.70151065356437,
"wateringFlag": 0,
"vibration": [
88,
88
],
"simulatedPercentage": 87.70151065356437,
"simulatedVibration": [
88,
88
]
},
{
"id": 1,
"day": "2015-06-04",
"mint": 18.600000000000001,
"maxt": 28.5,
"icon": 2,
"percentage": 0,
"wateringFlag": 0,
"vibration": [
0,
0
],
"simulatedPercentage": 0,
"simulatedVibration": [
0,
0
]
}
]
}

You can parse this json to extract the required data, using your favorite language. More information about the API and JSON responses can be found here: http://docs.rainmachine.apiary.io/

A more complex example:
In this example we’ll use information provided by an API call to perform another call. The task that we want to perform is to activate another weather parser on device that uses Met.no weather service. Once activated this parser will run periodically and fetch data from internet.

Step 1.
List all parsers installed on your system and retrieve the ID of the parser that you want to activate. For this /api/4/parser/ API call is used

curl -k https://192.168.12.175:8080/api/4/parser?access_token=eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab

The reply json will contain (the example bellow it’s a stripped down version of the actual response):

{
"parsers":
[
{
"lastRun": null,
"custom": false,
"enabled": false,
"uid": 5,
"name": "METNO Parser"
}
]
}

The key/value that we’re interested in is the "uid": 5 this is the ID of the Met.no parser.

Step 2.
Activate parser by issuing a POST with data and the /api/4/parser/ID/ API call:

curl -X POST -k -d '{"activate": true}' https://192.168.12.175:8080/api/4/parser/5/activate?access_token=eb426a74a46dfc46b6c991cb21a9901d917e1e57011599d79e248fab

The response should be: { "statusCode": 0, "message": "OK"} which means the API call succeeded in setting Met.no parser as active.

This concludes our quick start guide. You can get more information, sample code and full Parser API documentation here: http://docs.rainmachineparsers.apiary.io/#reference