Core Concepts of Making Requests

The following describes the common aspects of making API requests.

Request URLs

The URLs listed for each request are relative to the API request URL root. The API request roots are detailed in the Core Concepts section.

HTTP Method

API requests are made using the HTTP GET or POST methods, depending on the request type. Retrieving information is accomplished with a GET request whereas updating information is achieved with the POST request.

Encoding

Ensure that all requests are URL encoded. See HTML URL Encoding Reference for additional information. If your JSON is not encoded properly, the server may return an error when parsing the JSON string. The API requires content to be UTF-8 encoded.

Request Headers

All HTTP requests must specify the Content-Type header and encoding in in the request:

	Content-Type: application/json;charset=UTF-8                
                

Access Token

Each request, with the exception of the registration request must contain the authorization token which is returned by the token request.

When making a request, the access token must be specified in the Authorization header. The Authorization is of the type returned by the token_type response property returned from the authorization token request. It will look like this:

	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg         
                

POST Update Requests

Update (POST) requests are multi-operation capable, allowing the caller to update multiple properties of an object and multiple objects in one update operation. Most properties are not required when posting an update, only the required properties as specified by the object definition and the writable properties being changed need only to be sent.

It is strongly recommended that you do not send the complete object you received as part of a POST update. This will overwrite any changes to the object which may have occurred between the time you requested the original object and posted it again. Post only the properties you are changing and no more. The merging logic on the server and thermostat will ensure that all asynchronous updates occur in sequence and do not overwrite each other.

Common Request Parameters

The following common request parameters:

Parameter	HTTP Method	Example	Description
body	GET	?body={ "selection" [ "selectionType": ... ] }	The JSON GET request content. The JSON string must be properly URL encoded in the request URL.
format	GET, POST	?format=json	Optional. Informs the API that the request body contains JSON encoding. The API will respond with the same encoding. 'json' is the default and only encoding currently supported.

Request Paging

A page may be requested other than the first if the prior request indicated that more pages are available. To do so, append the Page Object with the "page" property and its value to the body of the GET Thermostats request. The default behaviour is to return the first page.

All GET Thermostats responses will contain page information which contains the number of pages available, as well as the total number of thermostats available. Each page is currently set to 25 thermostats per page.

Paged requests are equivalent to a read committed database isolation level. The data has a potential to change between page requests (phantom reads), namely if thermostats are added or removed from an account in between such requests.

Example Paged Response

A paged response will contain the Page object which contains all page information including the number of pages, and total number of results.

    {
        "page": {
            "page": 1,
            "totalPages": 3,
            "pageSize": 10,
            "total": 24
        },
        "thermostatList": [
            {
                "identifier": "123456789012",
                "name": "",
                "thermostatRev": "110128234025",
                "isRegistered": true,
                "modelNumber": "Smart",
                "serialNumber": "1",
                "productCode": "1",
                "lastModified": "2011-01-28 23:40:25",
                "alerts": []
            },
            // Repeated 
        ],
        "status": {
            "code": 0,
            "message": ""
        }
    

Example Page Request

{
	"selection": {
		"selectionType": "managementSet",
		"selectionMatch": "/"
	},
	"page": {
		"page": 2
	}
}

Request Selection

All requests contain the Selection object. This object defines the query criteria for thermostat or user resources. The selection object also defines the type of information to return in the response. The thermostat object and its related data is quite large. Under normal circumstances the caller may be only interested in only a subset of the available thermostat data. The selection is able to request only specific data about a thermostat in order to optimize processing and to reduce the amount of data going back and forth between the caller and the server.

See the Selection object definition.

API Responses

Responses returned by the API will always contain a body in JSON notation. The response will always contain the response status object along with any other returned objects, as appropriate. The status object represents the success or failure of the operation.

Note that the HTTP response codes for the Authorization requests and the API requests differ. The Authorization requests conform to the OAuth framework requirements for error codes. The API requests are simpler, with only two states, success and error. The status code returned indicates the type of error.

API Responses will contain the following headers:

	Content-Type: application/json                
                

The following HTTP response codes may be expected by the API client:

HTTP Response Code	Meaning
200	OK - success.
500	INTERNAL SERVER ERROR - an error occurred. Check response code for details.

See Response Codes for additional information.

Back To Top