- Ubidots Javascript Library
- Supported entities
- Supported field filters
- Installing
- Examples
- Ubidots API
This JS Library provides an intuitive and easy-to-use interface to interact with Ubidots' API. It allows sending data to devices and/or perform CRUD (Create, Read, Update, Delete) operations over the API-avaiable entities.
For the time being, the supported entities are:
The library supports all of Ubidots Field filters
Install the package running either:
npm install ubidots
or
yarn add ubidots
-
const allDevices = await Ubidots.devices.all();
-
const firstDevice = await Ubidots.devices.first(); // This is equivalent to const firstDevice = (await Ubidots.devices.all())[0];
-
const devicesPaginated = (await Ubidots.devices.paginate(1, 1000)).results;
-
const allDevicesLastActivity = await Ubidots.devices.addRawParam('fields', 'lastActivity').get();
-
const devices = await Ubidots.devices.addRawParams({ fields: ['lastActivity', 'variablesCount'] }).get();
-
const device = await Ubidots.devices .addRawParams({ label: 'temperature_device_1', fields: ['lastActivity', 'variablesCount'] }) .get();
-
// By label const temperatureDevice = await Ubidots.devices.where('label').is('temperature_device_1').first(); //By id const temperatureDevice = await Ubidots.devices.where('id').is('some-id').first();
-
const devicesByType = await Ubidots.devices.where('deviceType').exact('temperature-devices').get();
-
const allVariables = await Ubidots.variables.all();
-
const firstVariable = await Ubidots.variables.first(); // This is equivalent to const firstVariable = (await Ubidots.variables.all())[0];
-
const variablesPaginated = (await Ubidots.variables.paginate(1, 100)).results; //Equivalent to const variablesPaginated = (await Ubidots.variables.paginate()).results;
-
const allVariablesLastActivity = await Ubidots.variables.addRawParam('fields', 'lastActivity').get();
-
const variables = await Ubidots.variables.addRawParams({ fields: ['lastActivity', 'label'] }).get();
-
const variables = await Ubidots.variables .addRawParams({ id: '6452a727df1a8e000c103fce', fields: ['lastActivity', 'label'] }) .get();
-
const variableById = await Ubidots.variables.where('id').exact('6595770b9de79b000dce0eae').first();
-
const devicesByType = await Ubidots.devices.where('deviceType').exact('temperature-devices').get();
Get the device object and the variable object:
// Get the device object
const temperatureDevice = await Ubidots.devices.where('label').exact('temperature_device_1').first();
// Get the variable object
const temperatureVariable = await temperatureDevice.variables.where('label').exact('temperature').first();
- Send a value
temperatureVariable.sendDot(34);
- Send a value with timestamp
temperatureVariable.sendDot(40, new Date().getTime());
- Send a value with timestamp and context
temperatureVariable.sendDot(4, new Date().getTime(), { status: 'cold' });
Authentication using a valid Ubidots token is mandatory:
Ubidots.authenticate('BBFF-ubidots-token');
The following syntax provides access to the methods exposed by an Entity
Ubidots.<entity>.<method>(args)
Filters are also available for each entity, and the syntax is as follows:
Ubidots.<entity>.where(<entity-property>).<filter>(<value>)
//Ubidots.<entity>.<filter>.<modifier>.<method>(args)
- Description: Returns a list containing all the objects of an entity
- Arguments: None
-
Signature:
Ubidots.<entity>.all()
-
Return:
[{<entity_1>}, {<entity_2>}....{<entity_n>}]
- Examples:
- Description: Returns the first element in a list containing all the objects of the selected entity
- Arguments: None
-
Signature:
Ubidots.<entity>.first()
-
Return:
<entity>
- Examples
-
Description: Returns a
paginator
object corresponding to a paginated request to the selected entity, similar asall()
but paginated. -
Arguments:
-
page
:int
[optional. Default -> 1] => The page number to retrieve. -
size
:int
[optional. Default -> 100] => The maximum number of results per page.
-
-
Signature:
Ubidots.<entity>.paginate(, [page, size])
-
Return:
paginator
object - Examples
- Description: Creates a custom request by adding a Query param to it.
-
Arguments:
-
parameter
:str
[Mandatory] => The Query param to add to the request. -
value
:str | bool | int
[Mandatory] => The match criteria for the Query param.
-
-
Signature:
Ubidots.<entity>.addRawParam(<parameter>, <value>)
-
Return:
<entity>
- Examples
- Description: Creates a custom request by adding multiple a Query params and their values to the request.
-
Arguments:
-
queryObject
:Object
=> An object containing on the root level, keys representing they Query params, and their respective values is the matching criteria for the corresponding query param:
{ "queryParam1" : matchingCriteria1, . . . "queryParamN" : matchingCriteriaN, }
-
-
Signature:
Ubidots.<entity>.addRawParams(<queryObject>)
-
Return:
<entity>
- Examples
By applying Field filters on entitie's properties, it is possible to perform requests on a particular set of such entities.
For example, if it is required to retrieve data from all of the devices whose label start with the
When invoked, the paginate
method returns a paginator
object with the following properties and methods:
{
next(): `<paginator>`, // Returns a new instance of the paginator object, with the page property set to the next page (one ahead of the current page).
previous(): `<paginator>`, // Returns a new instance of the paginator object, with the page property set to the previous page (one less than the current page).
refresh(): `<paginator>`, // Re-executes the current request and returns the updated paginator object with refreshed data.
page: `int`, // Represents the current page number in the pagination sequence.
results: `Array[<entity>]`, // An array of entity objects present on the current page.
size: `int`, // Indicates the count of entity objects in the current page.
}