EVRYTHNG Developer Hub

Developer Hub

Welcome to the EVRYTHNG Developer Hub! Here you will find all the information you need to create your EVRYTHNG apps and integrations. We have conceptual guides, walkthroughs, and tutorials as well as a complete API reference.

BROWSE DOCUMENTATION VIEW API REFERENCE

Featured Pages

Blockchain Integration Hub

Read about the blockchain integrations that are available to use with EVRYTHNG.

Real-time Web Product Scanning

Learn how to easily scan and identify products in web apps.

GS1 Digital Link Integration

Learn how to easily link Thngs and products to a GS1 Digital Link.

evrythng.js

Suggest Edits

Current version: 4.7.2

evrythng.js is the official JavaScript SDK for developers writing web apps in the browser or server-side with platforms such as Node.js. It presents a fluent Promise-driven API that allows programmatic access to all resources available through the standard REST API.

Core Libraries

There are two main libraries that form the core of the Javascript SDK:

  • evrythng.js - the core version of evrythng.js intended to be used in public client applications and/or devices.

  • evrythng-extended.js - an extended version of evrythng.js that includes additional endpoints only available to the Account Operator. Since the Operator API key is mostly used for managing your Account structure and resources, it is not recommended to be used in customer client applications.

Plugins

In addition to the standard JS API, evrythng.js can be extended with plugins to add even more functionality. Available plugins include:

Installation

A summary of the various installation methods is shown here, but for detailed installation instructions, see the Installation section of the repository README.

Bower
Install: bower install evrythng --save
Include: <script src="bower_components/evrythng/dist/evrythng.js"></script>

CDN
Install: <script src="https://d10ka0m22z5ju5.cloudfront.net/toolkit/evrythng-js-sdk/evrythng-4.7.2.min.js"></script>
Include: Available globally as EVT

npm
Install: npm install evrythng --save
Include: Require as a dependency in the usual manner within the application JavaScript code:

const EVT = require('evrythng');

Setup Options

Once installed, evrythng.js can be optionally configured using setup(), with the following options:

  • apiUrl - String
    Change the default API host, such as https://api.evrythng.com.

  • fullResponse - Boolean
    Set to true to access the status or headers in responses. Can also be set on a per-request basis.

  • quiet - Boolean
    Set to true to prevent anything being output to the console.

  • geolocation - Boolean
    Set to true to ask for Geolocation when needed. When set to true, following resources will use the resolved coordinates: .action().create(), .thng().location().update(), .place().read().

  • timeout - Integer
    Set the default request timeout, in milliseconds

  • apiKey - String
    Set the authorization API key used for all raw requests

  • interceptors - Object array
    Register callbacks to be called on each request or response. An example is shown in the evrythng.js repository.

For example, to set a global timeout and disable geolocation:

EVT.setup({
  timeout: 5000,
  geolocation: false,
});

Scopes

The evrythng.js SDK includes scope objects that represent each type of API key, and allows the developer to make requests with that key. The following scopes are available:

  • App - Application API Key
  • User - Application User API Key
  • Device - Device API Key

There are additional Operator and TrustedApp scopes that are only available with the evrythng-extended.js SDK.

Most scopes are initialised in the same way by supplying the API key to use (except Device, which also requires the ID and API key):

const app = new EVT.App('$APPLICATION_API_KEY');

If the scope's metadata is required immediately, use $init to ensure this data has been fetched from the API and made ready for use:

const key = '$APPLICATION_API_KEY';

const app = new EVT.App(key).$init.then((app) => {
  console.log(`Loaded ${app.name}`);
});

Making requests

All requests are made via a scope object, and return promises. This provides an easy to read and intuitive interface to write a chain of functions to form the request as a whole.

In general, resource IDs are specified in that resource's function parameter list, and payloads are specified in the request method's parameter list. For example, to update a single Thng property:

const thngId = 'Um52tPXf6mshhMRRagVN2sHf';
const key = 'temperature_celsius';
const value = 34.2;

user.thng(thngId).property(key).update(value).then(console.log);

Or to read all products:

operator.product().read().then(console.log);

See the Function Reference section for a more complete list of available functions.

Parameters

Request query parameters mirror those in the conventional REST API, and are specified in the request method as a parameter using the params property. For example, applying a filter:

operator.thng().read({
  params: {
    filter: 'name=Test*'
  }
}).then(console.log);

Other examples of parameters specified in this way include: project, ids, perPage, withScopes, and context. Some of these are shown below for common scenarios:

// Find all thngs with a given name pattern and tags
operator.thng().read({
  params: {
    filter: {
      name: 'Device*',
      tags: 'electronic'
    }
  }
}).then(console.log);

// Specify filters as a string
operator.thng().read({
  params: {
    filter: 'tags=electronic&tags=device'
  }
}).then(console.log);

// Specify parameters such as project scope on creating a Thng
const thng = { name: 'Example Thng' };
operator.thng().create(thng, {
  params: {
    project: id
  }
}).then(console.log);

// Receive raw HTTP response instead of model entity
operator.thng().read({
  fullResponse: true
}).then(console.log);

// Read a single Thng with a certain tags pattern
operator.thng().read({
  params: {
    perPage: 1,
    filter: 'tags=equipment-*'
  }
}).then(console.log);

Function Reference

Actions

Scopes: Operator, User, TrustedApp, Device

.action(type).create(ActionDocument);  // Create an action
.action(type).read();                  // Read all actions of a type

.action(type, id).read();              // Read an action
.action(type, id).delete();            // Delete an action

Action Types

Scopes: Operator, TrustedApp, User

.actionType().create(ActionTypeDocument);      // Create an action type
.actionType().read();                          // Read all action types

.actionType(type).read();                      // Read a single action type
.actionType(type).update(ActionTypeDocument);  // Uppdate an action type
.actionType(type).delete();                    // Delete an action type

Application Users

Scopes: Operator, App

.appUser().create(ApplicationUserDocument);  // Create an Application User

.appUser(id).validate(activationCode);       // Activate an Application User

.user().read();                              // Read all Application Users

.user(id).read();                            // Read an Application User
.user(id).update(ApplicationUserDocument);   // Update an Application User
.user(id).delete();                          // Delete an Application User

Collections

Scopes: Operator, TrustedApp, User

.collection().create(CollectionDocument);            // Create a collection
.collection().read();                                // Read all collections

.collection(id).read();                              // Read a collection
.collection(id).update(CollectionDocument);          // Update a collection
.collection(id).delete();                            // Delete a collection

.collection(id).thng().read();                       // Read all Thngs in a collection
.collection(id).thng().update(thngIds);              // Add Thngs to a collection
.collection(id).thng().delete();                     // Remove all Thngs in a collection

.collection(id).thng(id).delete();                   // Remove a Thng from a collection

.collection(id).collection().read();                 // Read all collections in a collection
.collection(id).collection().create(collectionIds);  // Add collections to a collection
.collection(id).collection().delete();               // Remove all collections from a collection

Places

Scopes: Operator, App, TrustedApp, User

.place().create(PlaceDocument);    // Create a place
.place().read();                   // Read all places

.place(id).read();                 // Read a place
.place(id).update(PlaceDocument);  // Update a place
.place(id).delete();               // Delete a place

Products and Product Properties

Scopes: Operator, App, TrustedApp, User

.product().create(ProductDocument);                  // Create a product
.product().read();                                   // Read all products

.product(id).read();                                 // Read a product
.product(id).update(ProductDocument);                // Update a product
.product(id).delete();                               // Delete a product

.product(id).property().read();                      // Read product properties
.product(id).property().update(PropertiesDocument);  // Update product properties

.product(id).property(key).read();                   // Read product property history
.product(id).property(key).update(value);            // Update a product property
.product(id).property(key).delete();                 // Delete a product property

Projects, Applications, and Reactor

Scopes: Operator, Trusted

.project().create(ProjectDocument);                        // Create a project
.project().read();                                         // Read all projects

.project(id).read();                                       // Read a project
.project(id).update(ProjectDocument);                      // Update a project
.project(id).delete();                                     // Delete a project

.project(id).application().create(ApplicationDocument);    // Create an application
.project(id).application().read();                         // Read all applications in a project

.project(id).application(id).read();                       // Read an application
.project(id).application(id).update(ApplicationDocument);  // Update an application
.project(id).application(id).delete();                     // Delete an application

.project(id).application(id).reactor.log().read();         // Read Reactor logs

.project(id).application(id).reactor.script().read();                               // Read the Reactor script
.project(id).application(id).reactor.script().update(ReactorScriptDocument);        // Update the Reactor script

.project(id).application(id).reactor.schedule().create(ReactorScheduleDocument);    // Create a Reactor schedule
.project(id).application(id).reactor.schedule().read();                             // Read all Reactor schedules

.project(id).application(id).reactor.schedule(id).read();                           // Read a Reactor schedule
.project(id).application(id).reactor.schedule(id).update(ReactorScheduleDocument);  // Update a Reactor schedule
.project(id).application(id).reactor.schedule(id).delete();                         // Delete a Reactor schedule

Thngs and Thng Properties

Scopes: Operator, Trusted, User

.thng().create(ThngDocument);                     // Create a Thng
.thng().read();                                   // Read all Thngs

.thng(id).read();                                 // Read a Thng
.thng(id).update(ThngDocument);                   // Update a Thng
.thng(id).delete();                               // Delete a Thng

.thng(id).location().read();                      // Read a Thng's location
.thng(id).location().update(LocationDocument);    // Update a Thng's location

.thng(id).property().read();                      // Read Thng properties
.thng(id).property().update(PropertiesDocument);  // Update Thng properties

.thng(id).property(key).read();                   // Read a Thng property's history
.thng(id).property(key).update(value);            // Update a Thng property's history
.thng(id).property(key).delete();                 // Delete a Thng property's history

Other Requests

For all other requests (such as setting an account's role) that are not implemented in the evrythng.js SDK, it is possible to use EVT.api(). For example:

const accountId = 'UhpHrg39QCy9dsSddN8xhwnb';
const accessId = '59a02f8f59d2e12c003bc181';
const operatorApiKey = '$OPERATOR_API_KEY';

const update = {
  role: '59aeb3abb24413002c7d8651'
};

EVT.api({
  url: `/accounts/${accountId}/accesses/${accessId}`,
  authorization: operatorApiKey
  method: 'PUT',
  data: update
}).then(console.log);

evrythng.js

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.