nest-rest

Basic client for the Nest REST APIs, including support to obtain and revoke OAuth2 access codes.

Overview

const nest = require('nest-rest');

// Instantiate the client
const client = nest.restApiClient(token);

// Make a read request
client.read('/devices/thermostats', (error, result) => {
  // Process result
});

All the request methods can either be invoked with callbacks (as in the example above) or return promises:

client.read('/devices/thermostats').then(processResult);

async function makeRequest() {
  let result = await client.read('/devices/thermostats');
}

Once instantiated, the client can be used for multiple subsequent requests:

async function makeRequests() {
  let result = await client.read('/devices/thermostats');

  let otherResult = await client.read('/structures');
}

The client automatically follows 307 redirects, including storing the redirected location for subsequent requests.

Support for OAuth2 operations is available through a dedicated set of functions:

const oauth2 = require('nest-rest').oauth2;

oauth2.exchangeCodeForToken(code, (error, result) => {
  // Process result
});

Installation

npm install nest-rest --save

REST API client

The REST API client is instantiated as follows:

const nest = require('nest-rest');

const client = nest.restApiClient(token);

token must be a valid OAuth2 access token (string). Once instantiated, the client has the read/write privileges determined by the scope of its access token.

client.read(path[, callback])

Initiates an API read call. path specifies the requested data relative to https://developer-api.nest.com. Must be a string starting with /.

If present, callback must be a function that expects (error, result) as input parameters. Otherwise, if callback is not present, then nest.read() returns a promise to resolve result or to catch error.

The result value is an object defined as follows:

| Property | Description | |:-----------|:------------| | success | Boolean | | data | Object; data returned by the API server; only present if success is true | | response | Object; entire response returned by the API server; see the accept-json package documentation for details; only present if success is false |

client.write(path, data[, calllback])

Initiates an API write call. data must be an object with the data to be written. All the rest is the same as for the client.read() method.

OAuth2 utilities

Use of the OAuth2 functions specified in this section requires the OAuth2 client identifier and secret to be accessible through the OAUTH2_CLIENT_ID and OAUTH2_CLIENT_SECRET environment variables, respectively.

In addition, if you have registered multiple redirect URIs for the OAuth2 client and you intend to use a redirect URI other than the default one, then the selected redirect URI must be accessible through the OAUTH2_REDIRECT_URI environment variable. In all the other cases, the OAUTH2_REDIRECT_URI environment variable can be left undefined.

oauth2.generateAuthorizationUrl(state)

Returns the authorization URL as string. The OAuth2 flow starts with pointing the user's browser to this URL. state must be passed as string. Example:

const oauth2 = require('nest-rest').oauth2;

let authUrl = oauth2.generateAuthorizationUrl('4Ya0caMziW');

oauth2.exchangeCodeForToken(code[, callback])

Initiates a request to exchange an authorization code for an access token. code must be passed as string.

If present, callback must be a function that expects (error, result) as input parameters. Otherwise, if callback is not present, then oauth2.exchangeCodeForToken() returns a promise to resolve result or to catch error.

The result value is an object defined as follows:

| Property | Description | |:-----------|:------------| | success | Boolean | | token | String; only present if success is true | | expires | Integer; number of seconds remaining before the token expires from the time it was requested; only present if success is true | | response | Object; entire response returned by the API server; see the documentation of the accept-json package for details; only present if success is false |

Access tokens are generated with long term validity (10 years). Therefore, the expiration time can effectively be ignored.

oauth2.revokeToken(token[, callback])

Initiates a token revocation request. token must be passed as string.

Access tokens have long term validity. It is really a good practice to revoke them when not needed any longer.

If present, callback must be a function that expects (error, result) as input parameters. Otherwise, if callback is not present, then oauth2.revokeToken() returns a promise to resolve result or to catch error.

The result value is an object defined as follows:

| Property | Description | |:-----------|:------------| | success | Boolean | | revoked | Integer; equal to 1 if the submitted token was actually revoked; equal to 0 if the submitted token did no exist; only present if success is true | | response | Object; entire response returned by the API server; see the documentation of the accept-json package for details; only present if success is false |

Note that token revocation is considered successful both when the token is actually found and revoked (204 response from the server) and when it is simply not found (404 response from the server).