Response Format

The format of all API responses 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 follows a standard oauth2 client_credentials response format. The full authentication response format can be found in the OpenApi Specification.

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

200 Response:

{
  "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

422 Response:

{
  "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"
}