API documentation error & inconsistency

Smart Home & API API
1

Documentation Error:

Notice definition is “zone” (correct) and example is “device” (looks like a copy & paste error with the previous example):

Definition
https://api.rach.io/1/public/zone/:id

Examples
curl -X GET -H “Content-Type: application/json” -H “Authorization: Bearer 8e600a4c-0027-4a9a-9bda-dc8d5c90350d” https://api.rach.io/1/public/device/99363e8a-4418-11e4-b184-164230d1df90

Inconsistency?

Just curious why some API calls use params:

curl -X GET -H “Content-Type: application/json” -H “Authorization: Bearer 8e600a4c-0027-4a9a-9bda-ab8d5c90350d” https://api.rach.io/1/public/device/2a5e7d3c-c140-4e2e-91a1-a212a518adc5/event?startTime=1414818000000&endTime=1415739608103

and some use body:

curl -X PUT -H “Content-Type: application/json” -H “Authorization: Bearer 8e600a4c-0027-4a9a-9bda-dc8d5c90350d” -d ‘{ “id” : “d3e99d27-25e4-47dd-b354-1db5a84c99d7”, “duration” : 86400 }’ https://api.rach.io/1/public/device/rain_delay

2

RE: Inconsistency
RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content discusses the recommend standard for REST calls. Since this is a standard I’m not sure how closes the Rachio team follows them, but in general:

  • commands interacting with a whole Object (GET, DELETE, HEAD) will provide the id as a parameter in the the URL
  • commands interacting with fields (or attributes) of an Object (PUT, POST) will provide that data in the body