SiteWhere REST API

The SiteWhere REST API library provides a complete TypeScript implementation of the core SiteWhere object model along with comprehensive support for accessing all system functionality via strongly-typed APIs. This means you get syntax completion for all core SiteWhere APIs including the objects passed to and received from the interactions when using editors such as Visual Studio Code.

The SiteWhere REST APIs are packaged as a Node.js module and are available via NPM (https://www.npmjs.com/package/sitewhere-rest-api). Install the APIs into an existing Node-enabled project by issuing the following command:

npm install --save sitewhere-rest-api

After installation, the API elements may be imported individually along with various parts of the object model. For instance, the code below authenticates with the SiteWhere server to get a JWT, then sends an authenticated call for creating a device on the default tenant:

import * as SiteWhere from "sitewhere-rest-api";
import { AxiosResponse, AxiosInstance } from "axios";
import { IDeviceCreateRequest, IDevice } from "sitewhere-rest-api";

async function createDevice() {
  // Create Axios instance with basic auth for getting JWT.
  let auth: AxiosInstance = SiteWhere.Auth.createBasicAuthRequestForCredentials(
    "http://localhost:8080/sitewhere/authapi",
    "admin",
    "password"
  );

  // Extract JWT.
  let jwtResp: AxiosResponse<any> = await SiteWhere.AuthAPI.Jwt.getJwt(auth);
  let jwt: string = jwtResp.headers["x-sitewhere-jwt"];

  // Create Axios instance with JWT and tenant auth information.
  let axios: AxiosInstance = SiteWhere.Auth.createJwtRequest(
    "http://localhost:8080/sitewhere/api",
    jwt,
    "default",
    "sitewhere01234567890"
  );

  // Create request for new device.
  let request: IDeviceCreateRequest = {
    deviceTypeToken: "ipad",
    token: "123-TEST-4989485938",
    comments: "Created via REST API"
  };

  // Send device create message and use response.
  let resp: AxiosResponse<IDevice> = await SiteWhere.API.Devices.createDevice(
    axios,
    request
  );
  let device: IDevice = resp.data;
  console.log(`Created ${device.token} on ${device.createdDate}`);
}

createDevice();

Getting a JSON Web Token for Authentication

In order to use any of the SiteWhere APIs, a JWT must first be obtained using HTTP basic authentication to establish the identity of a system user making the call. The logic below obtains a JWT for user admin with password password. The JWT has a limited lifetime which is determined on the SiteWhere server that issues it. New JWTs may be obtained at any time since there is little-or-no server overhead for creating new ones.

  // Create Axios instance with basic auth for getting JWT.
  let auth: AxiosInstance = SiteWhere.Auth.createBasicAuthRequestForCredentials(
    "http://localhost:8080/sitewhere/authapi",
    "admin",
    "password"
  );

  // Extract JWT.
  let jwtResp: AxiosResponse<any> = await SiteWhere.AuthAPI.Jwt.getJwt(auth);
  let jwt: string = jwtResp.headers["x-sitewhere-jwt"];

Note that since the code uses await, this block would need to be nested in an async function. As an alternative, standard promise-based access is also supported.

Issuing API Calls for Specific Tenants

Since SiteWhere is a multitenant system, API calls must specify the tenant and associated authentication token in order to access the tenant-specific APIs. Before issuing API calls, create an Axios context. The example shown below will access the default tenant with authentication token sitewhere0123456789:

  // Create Axios instance with JWT and tenant auth information.
  let axios: AxiosInstance = SiteWhere.Auth.createJwtRequest(
    "http://localhost:8080/sitewhere/api",
    jwt,
    "default",
    "sitewhere0123456789"
  );

The same Axios context may be reused any number of times as long as the included JWT is still valid. If accessing multiple tenants, a separate context should be created for each tenant.