# Ubidots class

## Definition

The `Ubidots` class is the entrypoint of the library, providing sub-classes for interacting with each particular [supported entity](https://dev.ubidots.com/sdks/overview#supported-entities) from the API.  For example, to use the [devices API](https://docs.ubidots.com/reference/device-object) you can do:

```javascript
Ubidots.devices.<methods>
```

Here, the methods exposed by the `devices` sub-class allow you to consume the whole [devices API](https://docs.ubidots.com/reference/device-object).

## `Ubidots` class properties

|    Property   |                                           Description                                           |
| :-----------: | :---------------------------------------------------------------------------------------------: |
|    devices    |       Provides access to [devices](https://docs.ubidots.com/reference/device-object) API.       |
|   variables   |     Provides access to [variables](https://docs.ubidots.com/reference/variable-object) API.     |
|   dashboards  |    Provides access to [dashboards](https://docs.ubidots.com/reference/dashboard-object) API.    |
|     users     |         Provides access to [users](https://docs.ubidots.com/reference/user-object) API.         |
| organizations | Provides access to [organizations](https://docs.ubidots.com/reference/organization-object) API. |

{% hint style="info" %}
From now on, these properties will be addressed as `entity` or `entities` to reflect the fact that they enable interacting with that part (entity) of the API. With this in mind, `device entity` refers to the property of the `Ubidots` class that allows interacting with the [devices](https://docs.ubidots.com/reference/device-object) API.
{% endhint %}

## `Ubidots` class methods <a href="#ubidots-class-methods" id="ubidots-class-methods"></a>

<table><thead><tr><th width="148" align="center">Method</th><th width="197" align="center">Arguments</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center">authenticate</td><td align="center">A valid Ubidots token.</td><td align="center">Authenticates with the Ubidots API.</td></tr><tr><td align="center">setBaseUrl</td><td align="center">Custom API Host</td><td align="center">Configures a custom base URL for all API requests.</td></tr></tbody></table>

## Usage

### Authentication <a href="#authentication" id="authentication"></a>

Authentication using a valid [Ubidots token](https://help.ubidots.com/en/articles/590078-find-your-token-from-your-ubidots-account) is mandatory to use the library:

```javascript
Ubidots.authenticate('BBFF-ubidots-token');
```

### Custom API Host <a href="#instantiation" id="instantiation"></a>

Configure a custom base URL when connecting to dedicated Ubidots deployment:

```javascript
Ubidots.setBaseUrl('https://custom.api.ubidots.com/api')
```

### Instantiation <a href="#instantiation" id="instantiation"></a>

This class is implemented as a singleton which is instantiated when it is exported, thus, there is no need for creating an instance of it. Instead, you must use it directly:

```javascript
// Import the class
const { Ubidots } = require('@ubidots/ubidots-javascript-library');
// Call 'authenticate' method with no prior instantation of 'Ubidots'
Ubidots.authenticate('ubidots-valid-token');
```

### General syntax <a href="#general-syntax" id="general-syntax"></a>

As stated before, the Ubidots class exposes its [methods](https://dev.ubidots.com/sdks/javascript/ubidots-class/get-methods) through [`entities`](#ubidots-class-properties) for a particular part of the API such as devices or variables, thus providing the following syntax:

```javascript
Ubidots.<entity>.<getMethod>(, [args]);
```

### Filters syntax <a href="#filters-syntax" id="filters-syntax"></a>

[Field filtering](https://docs.ubidots.com/reference/field-filters) is available for each [`entity`](#ubidots-class-properties) through the following syntax:

```javascript
Ubidots.<entity>.<filterMethod>(args).<getMethod>(, [args]);
```

**Here:**

* `<entity>` is any of the valid [entities](#ubidots-class-properties).
* `<filterMethod>` is either of these 2 methods:
  * [`where()`](https://dev.ubidots.com/sdks/javascript/ubidots-class/filter-methods)
  * [`addRawParams()`](https://dev.ubidots.com/sdks/javascript/ubidots-class/filter-methods)
* `<getMethod>` Either of the below methods to retrieve [`entities`](#ubidots-class-properties):
  * [`all()`](https://dev.ubidots.com/sdks/javascript/ubidots-class/get-methods)
  * [`get()`](https://dev.ubidots.com/sdks/javascript/ubidots-class/get-methods)
  * [`first()`](https://dev.ubidots.com/sdks/javascript/ubidots-class/get-methods)
  * [`paginate()`](https://dev.ubidots.com/sdks/javascript/ubidots-class/get-methods)

{% hint style="info" %}
Neither `where` nor `addRawParams` methods perform the request to the API, they just build the URL with the corresponding query params. In order to actually perform the request, it is required to concatenate a calling to any of the [`<getMethods>`](https://dev.ubidots.com/sdks/javascript/ubidots-class/get-methods) after the filter statements.
{% endhint %}