Simple API Access App Example
Overview
This simple NodeJS Express app illustrates how to create an API Access SmartApp that connects to your SmartThings
account with OAuth2 and allows you to execute manually run routines (which are called "scenes" in the API).
It's a very simple app that stores the access and refresh tokens in session state. It uses the
express-session in-memory session store,
so you will lose your session data
when you restart the server, but you can use another
compatible session store
to make the session persist between server
restarts. This example uses the
@SmartThings/SmartApp SDK NPM module for making the
API calls to list and execute scenes.
Files and directories
- public
- stylesheets -- stylesheets used by the web pages
- views
- error.ejs -- error page
- index.ejs -- initial page with link to connect to SmartThings
- scenes.ejs -- page that displays scenes and allows them to be executed
- server.js -- the Express server and SmartApp
- .env -- file you create with app client ID and client secret
Getting Started
Prerequisites
Instructions
1. Clone this GitHub repository, cd into the directory, and install the Node modules with NPM:
git clone https://github.com/SmartThingsCommunity/api-app-minimal-example-js.git
cd api-app-minimal-example-js
npm install
2. Register your app with SmartThings using the CLI
Start with the smartthings apps:create command to create a new app. You will be prompted for the required
information. The following is an example of the output from the command:
~ % smartthings apps:create
? What kind of app do you want to create? (Currently, only OAuth-In apps are supported.) OAuth-In App
More information on writing SmartApps can be found at
https://developer.smartthings.com/docs/connected-services/smartapp-basics
? Display Name My API App
? Description Allows scenes to be executed
? Icon Image URL (optional)
? Target URL (optional)
More information on OAuth 2 Scopes can be found at:
https://www.oauth.com/oauth2-servers/scope/
To determine which scopes you need for the application, see documentation for the individual endpoints you will use in your app:
https://developer.smartthings.com/docs/api/public/
? Select Scopes. r:locations:*, r:scenes:*, x:scenes:*
? Add or edit Redirect URIs. Add Redirect URI.
? Redirect URI (? for help) http://localhost:3000/oauth/callback
? Add or edit Redirect URIs. Finish editing Redirect URIs.
? Choose an action. Finish and create OAuth-In SmartApp.
Basic App Data:
─────────────────────────────────────────────────────────────────
Display Name My API App
App Id 037bcd6c-xxxx-xxxx-xxxx-xxxxxxxxxxxx
App Name amyapiapp-a8b20801-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Description Allows scenes to be executed
Single Instance true
Classifications CONNECTED_SERVICE
App Type API_ONLY
─────────────────────────────────────────────────────────────────
OAuth Info (you will not be able to see the OAuth info again so please save it now!):
───────────────────────────────────────────────────────────
OAuth Client Id 689f9823-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OAuth Client Secret 3a2c39d8-xxxx-xxxx-xxxx-xxxxxxxxxxxx
───────────────────────────────────────────────────────────
3. Create a .env file in the root directory of the project
Add the PORT, SERVER_URL, APP_ID, CLIENT_ID, and CLIENT_SECRET properties from the output of the smartthings apps:create command. For example:
PORT=3000
SERVER_URL=http://localhost:3000
APP_ID=037bcd6c-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_ID=689f9823-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_SECRET=3a2c39d8-xxxx-xxxx-xxxx-xxxxxxxxxxxx
4. Start your server:
node server.js
5. Connect your app to SmartThings
Go to http://localhost:3000, log in with your SmartThings account credentials, and
choose a location. You should see a page with the location name as a header and button for
each scene in that location. Clicking the button should execute the scene. If you don't see
any buttons you may need to create some scenes using the SmartThings mobile app.