REST Overview

REST is a lightweight, stateless web service standard that you can use within your products for ad-hoc one-off calls, proof-of-concept labs, troubleshooting, apps that poll approximately every minute, and refresh button implementations.

The REST interface uses the Nest API Data Model URL as an endpoint.

In REST, there is an OAuth token mapped to a path in the API data model. Each token is associated with a single end user. The token means a user has authorized the developer to access a path in the data model. The Nest API cloud evaluates the token against the requested path and either sends an error or sends the requested information.

Suppose a user wants to provide status information about the occupancy of their home so that the garage door opens when the user arrives home. A token is evaluated to get the Home & Away state of the structure.

To stay updated on the occupancy state, REST calls might be made every minute to determine the home or away status. The Nest API evaluates the token and returns the answer. In response to each call, the information is returned and then the TCP connection is closed. Each call generates a new TCP connection.

Keep in mind the following points about Nest's implementation:

Not supported:

  • POST
  • Writing priorities for the REST API
  • Writing server values from the REST API
  • Retrieving and updating security rules

REST and rate limits

To prevent overutilization of the Nest service, we limit the number of token has a limited number of read/write calls.

For more info, see Data Rate Limits.

REST and redirects

Another consideration when using REST is that your product must also handle 307 redirects.