Help get this topic noticed by sharing it on Twitter, Facebook, or email.

swagger.json API documentation to avoid following documentation issues

Does ecobee have a swagger.json or other formal documentation for their RESTful API other than the online documentation? The reason I ask is because the ecobee online API documentation is littered with errors such as

1-In the documentation page for Get Meter Report the Response Properties table lists startDate, startInterval, endDate, endInterval, meters, and reportList as properties. However the Example response at the bottom of the documentation page shows a JSON response with only reportList and status.

a-I have actually invoked this API against my Thermostat and can confirm that the shown JSON response is correct and that the properties startDate, startInterval, endDate, endInterval, and meters are not returned Should these parameters be removed from the Response Properties table?

b-The Response Properties table is missing the status property

2-In the documentation page for all the following requests (POST Add Set, POST Remove Set, POST Rename Set, POST Move Set, POST Add User, POST Remove User, POST Unregister User, POST Update User, POST Register Thermostat, POST Unregister Thermostat, POST Move Thermostat, and POST Assign Thermostat) the Response Properties table only lists status as a possible property. However the Example response at the bottom of all these documentation pages shows the following JSON
{
"success": true,
"status": {
"code": 0,
"message": ""
}
}

a-Is success a valid return parameter? Unfortunately I don't have an EMS or Utility account so cannot check this.
b-What does the success property add that status would not indicate?

3-In the documentation page for POST Issue Demand Response the Response Properties table lists demandResponseRef and status as possible properties. However the Example response at the bottom of the documentation page shows the following JSON
{
"status": {
"code": 0,
"message": ""
}
}

a-Surely, the demandResponseRef property must always be sent in the JSON response? Unfortunately I don't have an EMS or Utility account so cannot check this.

4-In the documentation page for POST Cancel Demand Response the Request Properties table lists demandResponseRef as a required property. The Example request though shows the following JSON
{
"operation":"cancel",
"demandResponse": {
"demandResponseRef":"c253a12e0b3c3c93800095"
}
}
a-Is demandResponseRef a top level property as the Request Properties table indicates, or a sub property of demandResponse as the JSON shows? Unfortunately I don't have an EMS or Utility account so cannot check this.

Thanks
2 people have
this question
+1
Reply