Changes in API from v0.0.7 beta -> v1.0.0

API Specification Type change

The API specification has been converted from swagger (aka OpenApi Specification 2.0, or OAS2) to OpenApi Specification 3.0 (OAS3)

The format is largely the same, with some sections renamed or moved. More information around the new features and changes in the specification can be found at https://swagger.io/blog/news/whats-new-in-openapi-3-0/

If swagger codegen was formerly being used at all to generate SDKs for interfacing with the API, openapi codegen can now be used instead: https://github.com/OpenAPITools/openapi-generator

Previously we had exposed an endpoint to download the swagger spec here: https://api.sb.ecobee.com/docs/swagger.json

This has now changed to: https://api.sb.ecobee.com/docs/openapi.json

Response format change

We've changed the response format of the API, and standardized all routes to follow the new format.

The new format is based on jsend. This is a fairly simple format, but flexible enough to handle many types of data.

The only route that follows a different format is the /token route. It's response format is still the same as before and is reflected that way in the new openapi spec.

Success Response

Success responses will have the following keys:

status: Will be set to "success".
data: Contains any data returned by the API call. If the call returns no data, data will be set to null.

Success Example

GET /api/v1/thermostats/:thermostatId

{
  "status": "success",
  "data": {
    "id": "511863314842",
    "buildingId": "5d67ec8293d7eb0013d04f8e",
    "name": "MyThermostat",
    "timeZoneOffsetMinutes": -300
  }
}

Fail Response

The fail response is for requests that have been rejected due to invalid data in the request. This includes missing fields, badly formatted fields, and fields with invalid data.

Fail responses will have the following keys:

status: Will be set to "fail".
data: Details on why the request failed. If the reasons for failure correspond to POST values, the response object's keys SHOULD correspond to those POST values.

Fail Example

POST /api/v1/buildings

{
  "status": "fail",
  "data": {
    "postalCode": "Building must have a valid postal code"
  }
}

Error Response

Error responses are for all other types of errors, eg, authorization, permission, server errors, etc.

Error responses will have the following keys:

status: Will be set to "error".
message: A meaningful, end-user-readable or log-worthy message, explaining what went wrong.

Optionally the following keys may exist:

code: A numeric code corresponding to the error, if applicable
data: A generic container for any other information about the error, eg. the conditions that caused the error

Error Example

GET /api/v1/thermostats/1234567890

404 Response:

{
  "status": "error",
  "message": "thermostatId was not found"
}

Thermostat Route changes

The GET thermostat route, /api/v1/thermostats/{thermostatId} has been broken up into a number of sub routes, with many of the fields from the base route moving to these new routes. The following fields remain on the base thermostat response: name, id, buildingId, timeZoneOffsetMinutes

New Sub Routes

/api/v1/thermostats/{thermostatId}/alerts
- This route now contains the information from the alerts field that was formerly on the base thermostat route
/api/v1/thermostats/{thermostatId}/events
- This route now contains the information from the holds field that was formerly on the base thermostat route
/api/v1/thermostats/{thermostatId}/sensors
- This route now contains the information from the sensors field that was formerly on the base thermostat route
/api/v1/thermostats/{thermostatId}/status
- Much of the data has been moved from the base thermostat route to this new one. Most of the dynamically changing fields now exist here to make polling for this type of frequently updated data easier without having to poll the whole thermostat object.
- These are the fields that have moved:
  - comfortSetting
  - desiredCoolRange
  - desiredDehumidity
  - desiredHeatRange
  - desiredHumidity
  - heatCoolMinDelta
  - humidity
  - hvacMode
  - isConnected
  - runningEquipment
  - setPoint
  - temperature
/api/v1/thermostats/{thermostatId}/weather
- This route now contains the information from the weatherForecasts field that was formerly on the base thermostat route

Thermostat/Building ID change

The thermostat and building objects formerly had fields called thermostatId and buildingId respectively. These fields have now been renamed to just id on those objects. Moving forward, any objects that have an id associated with them, will have an id field.

Building Route Changes

The GET building route, /api/v1/buildings/{buildingId}, has been modified slightly. The thermostats field (representing a list of thermostats found in that building) has now been moved from the building summary response to a new sub route: /api/v1/buildings/{buildingId}/thermostats.