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.
Installation
A summary of the various installation methods is shown here, but for detailed installation instructions, see the Installation section of the repository README.
CDN
Install with a script tag:
<script src="https://d10ka0m22z5ju5.cloudfront.net/js/evrythng/6.0.0/evrythng-6.0.0.js"></script>
Include: Available globally as evrythng
npm
Install: npm install --save evrythng
Include: Require as a dependency in the usual manner within the application JavaScript code:
const evrythng = require('evrythng');
// Or using ES6 modules
import * as evrythng from '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 ashttps://api.us.evrythng.io/v2. If not specified, this is determined using values given forapiVersionandregion. -
fullResponse- Boolean
Set totrueto access thestatusorheadersin responses. Can also be set on a per-request basis. -
quiet- Boolean
Set totrueto prevent anything being output to the console. -
geolocation- Boolean
Set totrueto ask for Geolocation when needed. When set totrue, 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 theevrythng.jsrepository. -
defaultShortDomain- String
Set the default short domain to be used when dealing with redirections. -
apiVersion- Number
Set which API version to use:1or2. By default, apiVersion is2. Refer to the v2, or v1 (legacy) guides. -
region- String
Set region URL for defined API version. There are two supported regions:us, which is set by default, andeu.
For example, to set a global timeout and disable geolocation:
evrythng.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 for apiVersion:2 are available:
Operator- Operator API KeyAccessToken- Access Token API Key
Operator and AccessToken scopes can have a different set of permissions, which is defined on access policy and assigned during creation of operator access and access token.
The following scopes for apiVersion:1 are available:
Operator- Operator API KeyApplication- Application API KeyTrustedApplication- Trusted Application API KeyActionApp- Application API KeyUser- Application User API KeyDevice- Device API Key
Most scopes are initialized in the same way by supplying the API key to use (except Device, which also requires the ID and API key):
const evrythng = require('evrythng');
const app = new evrythng.Application(APPLICATION_API_KEY);
// Or using destructuring
import { Application } from 'evrythng';
const app = new Application(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 app = new evrythng.Application(APPLICATION_API_KEY);
// Wait for scope to read its data before using its customFields
app.init()
.then(() => console.log(app.customFields));
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, the format flows from the scope, to the resource type (such as thng or collection), to the resource method.
Methods include create, read, update, delete, rescope, upsert, find, stream, and streamPages.
In general, resource IDs are specified in that resource's method parameter list, and payloads are specified in the request method's parameter list. For example, to update a single Thng:
const thngId = 'Um52tPXf6mshhMRRagVN2sHf';
const payload = { tags: ['updated'] };
// Using Promises
user.thng(thngId).update(payload)
.then(console.log);
// Or async/await
const res = await user.thng(thngId).update(payload);
console.log(res);
Or to read a single page of products:
// Using Promises
operator.product().read()
.then(console.log);
// Or async/await
const products = await operator.product().read();
console.log(products);
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 either the params property, or chainable setters. For example, applying a filter:
// Using a params object
const params = {
filter: 'name=Test*',
perPage: 100,
};
operator.thng()
.read({ params })
.then(console.log);
// Or using chainable setters
operator.thng()
.setFilter('name=Test*')
.setPerPage(100)
.read()
.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:
// Specify filter as an object
const params = {
filter: {
name: 'Pallet*',
tags: 'shipped',
},
};
user.thng().read({ params })
.then(console.log);
// Specify filters as a string
const params = { filter: 'name=Pallet*&tags=shipped' };
user.thng().read({ params })
.then(console.log);
// Specify parameters such as project scope on creating a Thng
const projectId = 'UF6HgyNFVDswQKRRwhPK3kCg';
const payload = { name: 'Example Thng' };
const params = { project: projectId };
user.thng().create(payload, { params })
.then(console.log);
// Receive raw HTTP fetch response instead of model entity
user.product().read({ fullResponse: true })
.then(console.log);
// Read a single Thng with a certain tags pattern with context and scopes
const params = {
perPage: 1,
filter: 'tags=batch-*',
withScopes: true,
context: true,
};
user.action().read({ params })
.then(console.log);
The same examples using chainable setters:
// Specify filter as an object
user.thng()
.setFilter('name=Pallet*&tags=shipped')
.read()
.then(console.log);
// Specify parameters such as project scope on creating a Thng
const projectId = 'UF6HgyNFVDswQKRRwhPK3kCg';
const payload = { name: 'Example Thng' };
user.thng()
.setProject(projectId)
.create(payload)
.then(console.log);
// Read a single Thng with a certain tags pattern with context and scopes
user.action()
.setPerPage(1)
.setFilter('tags=batch-*')
.setWithScopes()
.setContext()
.read()
.then(console.log);
Function Reference for apiVersion:2
apiVersion:2Operator and AccessToken scopes
Operator and AccessToken scopesAccounts, Account Accesses, Short Domains, Domains
.sharedAccount().read(); // Read all shared accounts
.sharedAccount(id).read(); // Read a single shared account
.sharedAccount(id).update(AccountDocument); // Update a shared account
.sharedAccount(id).access().read(); // Read all account accesses
.sharedAccount(id).access(id).read(); // Read a single account access
.sharedAccount(id).access(id).update(AccessDocument); // Update a single account access
.sharedAccount(id).shortDomain().read(); // Read a single account's short domains
.sharedAccount(id).domain().read(); // Read a single account's domains
Operator Accesses
.sharedAccount(id).operatoAccess().read(); // Read all account's operator accesses
.sharedAccount(id).operatoAccess().create(OperatorAccessDocument); // Create account's operator access
.sharedAccount(id).operatoAccess(id).read(); // Read a single account's operator access
.sharedAccount(id).operatoAccess(id).update(OperatorAccessDocument); // Update a single account's operator access
.sharedAccount(id).operatoAccess(id).delete(); // Delete a single account's operator access
Access Policy
.accessPolicy().read(); // Read all access policies
.accessPolicy().create(AccessPolicyDocument); // Create access policy
.accessPolicy(id).read(); // Read a single access policy
.accessPolicy(id).update(AccessPolicyDocument); // Update a single access policy
.accessPolicy(id).delete(); // Delete a single access policy
Access Token
.accessToken().read(); // Read all access tokens
.accessToken().create(AccessTokenDocument); // Create access token
Actions
.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
.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
Collections
.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
Me
.me().read(); // Read API key access
Places
.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, Product Properties, Product Redirections
.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
.product(id).redirection().create(RedirectionDocument); // Create a product's redirection
.product(id).redirection().read(); // Read a product's redirection
.product(id).redirection().update(RedirectionDocument); // Update a product's redirection
.product(id).redirection().delete(); // Delete a product's redirection
Projects, Applications, Reactor, Application Redirector
.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).secretKey().read(); // Read Trusted Application API Key
.project(id).application(id).redirector().read(); // Read an application
.project(id).application(id).redirector() // Update an application
.update(ApplicationDocument);
.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 the Reactor script
.update(ReactorScriptDocument);
.project(id).application(id).reactor.schedule() // Create a Reactor schedule
.create(ReactorScheduleDocument);
.project(id).application(id).reactor.schedule() // Read all Reactor schedules
.read();
.project(id).application(id).reactor.schedule(id) // Read a Reactor schedule
.read();
.project(id).application(id).reactor.schedule(id) // Update a Reactor schedule
.update(ReactorScheduleDocument);
.project(id).application(id).reactor.schedule(id) // Delete a Reactor schedule
.delete();
Purchase Orders
.purchaseOrder().create(PurchaseOrderDocument); // Create a purchase order
.purchaseOrder().read(); // Read all purchase orders
.purchaseOrder(id).read(); // Read a purchase order
.purchaseOrder(id).update(); // Update a purchase order
.purchaseOrder(id).delete(); // Delete a purchase order
Account Redirector
.redirector().read(); // Read account Redirector
.redirector().update(RedirectorDocument); // Update account Redirector
Shipment Notices
.shipmentNotice().create(ShipmentNoticeDocument); // Create a shipment notice
.shipmentNotice().read(); // Read all shipment notices
.shipmentNotice(id).read(); // Read a shipment notice
.shipmentNotice(id).update(); // Update a shipment notice
.shipmentNotice(id).delete(); // Delete a shipment notice
Thngs, Thng Properties, Thng Redirections, Thng Commission State
.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
.thng(id).redirection().create(RedirectionDocument); // Create a Thng's redirection
.thng(id).redirection().read(); // Read a Thng's redirection
.thng(id).redirection().update(RedirectionDocument); // Update a Thng's redirection
.thng(id).redirection().delete(); // Delete a Thng's redirection
.thng(id).commissionState().read(); // Read Thng commissioning state
Function Reference for the legacy version apiVersion:1
apiVersion:1Accounts, Account Accesses, Short Domains, Domains
Scopes: Operator
.sharedAccount().read(); // Read all shared accounts
.sharedAccount(id).read(); // Read a single shared account
.sharedAccount(id).update(AccountDocument); // Update a shared account
.sharedAccount(id).access().read(); // Read all account accesses
.sharedAccount(id).access(id).read(); // Read a single account access
.sharedAccount(id).access(id).update(AccessDocument); // Update a single account access
.sharedAccount(id).shortDomain().read(); // Read a single account's short domains
.sharedAccount(id).domain().read(); // Read a single account's domains
Actions
Scopes: Operator, User, TrustedApplication, 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, TrustedApplication, 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, Application
.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
Batches and Tasks
Scopes: Operator
.batch().create(BatchDocument); // Create a batch
.batch().read(); // Read all batches
.batch(id).read(); // Read a batch
.batch(id).update(); // Update a batch
.batch(id).delete(); // Delete a batch
.batch(id).task().create(TaskDocument); // Create a task on a batch
.batch(id).task().read(); // Read all tasks
.batch(id).task(id).read(); // Read a task
Collections
Scopes: Operator, TrustedApplication, 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
Files
Scopes: Operator
.file().create(FileDocument); // Create a file
.file().read(); // Read all files
.file(id).read(); // Read a file
.file(id).delete(); // Delete a file
Places
Scopes: Operator, Application, TrustedApplication, 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, Product Properties, Product Redirections
Scopes: Operator, Application, TrustedApplication, 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
.product(id).redirection().create(RedirectionDocument); // Create a product's redirection
.product(id).redirection().read(); // Read a product's redirection
.product(id).redirection().update(RedirectionDocument); // Update a product's redirection
.product(id).redirection().delete(); // Delete a product's redirection
Projects, Applications, Reactor, Application Redirector
Scopes: Operator, TrustedApplication
.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).secretKey().read(); // Read Trusted Application API Key
.project(id).application(id).redirector().read(); // Read an application
.project(id).application(id).redirector() // Update an application
.update(ApplicationDocument);
.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 the Reactor script
.update(ReactorScriptDocument);
.project(id).application(id).reactor.schedule() // Create a Reactor schedule
.create(ReactorScheduleDocument);
.project(id).application(id).reactor.schedule() // Read all Reactor schedules
.read();
.project(id).application(id).reactor.schedule(id) // Read a Reactor schedule
.read();
.project(id).application(id).reactor.schedule(id) // Update a Reactor schedule
.update(ReactorScheduleDocument);
.project(id).application(id).reactor.schedule(id) // Delete a Reactor schedule
.delete();
Purchase Orders
Scopes: Operator, TrustedApplication, User
.purchaseOrder().create(PurchaseOrderDocument); // Create a purchase order
.purchaseOrder().read(); // Read all purchase orders
.purchaseOrder(id).read(); // Read a purchase order
.purchaseOrder(id).update(); // Update a purchase order
.purchaseOrder(id).delete(); // Delete a purchase order
Account Redirector
Scopes: Operator
.redirector().read(); // Read account Redirector
.redirector().update(RedirectorDocument); // Update account Redirector
Roles, Permissions, and Role Policies
Scopes: Operator
.role().create(RoleDocument); // Create a role
.role().read(); // Read all roles
.role(id).read(); // Read a role
.role(id).update(RoleDocument); // Update a role
.role(id).delete(); // Delete a role
.role(id).permission().read(); // Read role permissions
.role(id).permission().update(RolePermissionDocument); // Update role permissions
Shipment Notices
Scopes: Operator
.shipmentNotice().create(ShipmentNoticeDocument); // Create a shipment notice
.shipmentNotice().read(); // Read all shipment notices
.shipmentNotice(id).read(); // Read a shipment notice
.shipmentNotice(id).update(); // Update a shipment notice
.shipmentNotice(id).delete(); // Delete a shipment notice
Thngs, Thng Properties, Thng Redirections, Thng Commission State
Scopes: Operator, TrustedApplication, 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
.thng(id).redirection().create(RedirectionDocument); // Create a Thng's redirection
.thng(id).redirection().read(); // Read a Thng's redirection
.thng(id).redirection().update(RedirectionDocument); // Update a Thng's redirection
.thng(id).redirection().delete(); // Delete a Thng's redirection
.thng(id).commissionState().read(); // Read Thng commissioning state
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 api(). For example:
evrythng.api({ url: '/time' })
.then(console.log);
Updated 5 months ago