evrythng.js
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 forapiVersion
andregion
. -
fullResponse
- Boolean
Set totrue
to access thestatus
orheaders
in responses. Can also be set on a per-request basis. -
quiet
- Boolean
Set totrue
to prevent anything being output to the console. -
geolocation
- Boolean
Set totrue
to 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.js
repository. -
defaultShortDomain
- String
Set the default short domain to be used when dealing with redirections. -
apiVersion
- Number
Set which API version to use:1
or2
. 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:2
Operator
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:1
Accounts, 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 over 1 year ago