loader

Leave your contacts

We have received your request

Build your first project before our response.
It's free!

Create project
REST APIObjects

Objects of control

Work in the Rightech IoT Cloud platform is organized around the objects of control. They are a representation of real-world objects that are monitored and controlled.

Typical description of the object of control:

interface Object {
    _id      : String;  /* Internal identifier in the system */
    id       : String;  /* User Asset Identifier  */
    model    : String;  /* Identifier of the model of the control object */
    status   : String;  /* The text status of the object */
    state    : Packet;  /* Latest data packet */
}

In addition to the global identifier _id another identifier id, is defined that is used to communicate with external data transfer systems. The data packet of the object isn’t fixed, it is determined depending on the model of the device. The minimum set of parameters is the identifier and the registration time.

Typical description of a data packet:

interface MinPacket {
    _id     : String;    /* Package id */
    _ts     : Number;    /* Server Time (microseconds) */ 
    time    : Number;    /* Device or server packet registration time (milliseconds) */
    online  : Boolean;
}

You may notice that in the _ts and time fields the server time can be indicated simultaneously. This is because if the object does not register the current time on its own and does not send data about it to the platform, then the default server time will be indicated in the time field. 

When additional parameters are added to the model, they are added to the object’s data package format.

Example

interface Packet extends MinPacket {
    lat     : Number;  /* Latitude */
    lon     : Number;  /* Longitude */    
    height  : Number,  /* Height above sea level in metres */
    angle   : Number,  /* Angle of rotation in degrees */
    speed   : Number;  /* Instant speed in km / h */

}

The main operations that can be reproduced with objects through the use of the API include:

  1. Getting a list of objects;
  2. Getting information about one object;
  3. Creating an object;
  4. Object editing;
  5. Deleting an object;
  6. Getting object data log;
  7. Sending commands;
  8. WebSocket events.

Getting a list of objects

To request a list of objects created earlier and added to the user for access, you need to send a request GET /api/v1/objects. The response from the web server will show an array of objects in json format.

Request

GET /api/v1/objects HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

[
    {
        "_id": "5d8a25c1d0025e0012fb84b3",
        "model": "5d8a1ef2d0025e0012fb76c6",
        "id": "mqtt-z86s58",
        "name": "Object 01",
        "status": "ok",
        "active": true,
        "group": "5d8a18d4d0025e0012fb6a31",
        "models": {
            "id": "5d8a1ef2d0025e0012fb76c6"
        }
    },
    {
        "_id": "5d8a3612d0025e0012fba724",
        "model": "5d8a3319d0025e0012fba0fa",
        "id": "mqtt-lf2d0d",
        "name": "Object 02",
        "status": "ok",
        "active": true,
        "group": "5d8a18d4d0025e0012fb6a31",
        "models": {
            "id": "5d8a3319d0025e0012fba0fa"
        }
    }
]

Getting information about one object

To get information about one object, you must specify its identification number assigned to it by the system. In response, the server will receive the configuration of the object and the result of the request.

Request

GET /api/v1/objects/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

{
    "_id": "5d8a3612d0025e0012fba724",
    "model": "5d8a3319d0025e0012fba0fa",
    "id": "mqtt-elisalena99-lf2d0d",
    "name": "mqtt-elisalena99-lf2d0d",
    "status": "ok",
    "active": true,
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "success": true
}

Creating an object

To register a new control object in the system, it is necessary to send  POST /api/v1/objects request indicating the required fields. The required fields are  id and name. The response will indicate the generated configuration of the created object and the result of the request.

Request

POST /api/v1/objects HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{ 
  "id":"SOME_OBJECT_ID", 
  "name":"SOME_OBJECT_NAME",
}

Response

HTTP/1.1 200 OK

{
    "id": "someID3458374",
    "name": "Object 03",
    "model": "5d8a3319d0025e0012fba0fa",
    "status": "ok",
    "active": true,
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "time": 1569340547109,
    "_id": "5d8a3c83d0025e0012fbb4ca",
    "success": true
}

Object editing

When making some changes to the configuration of the object, a PATCH /api/v1/objects/:id request is sent with the identification number of this object. It is worth considering that when making any changes to the essence, it is necessary to build on its structure. Accordingly, the user can change any values in the fields of the object, for example, change its status. In response, the server will receive the configuration of the object, taking into account the changes made and the result of the request.

Request

PATCH /api/v1/objects/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{ 
    "status": "Broken"
}

Response

HTTP/1.1 200 OK

{
    "_id": "5d8a3c83d0025e0012fbb4ca",
    "id": "someID3458374",
    "name": "Object 03",
    "model": "5d8a3319d0025e0012fba0fa",
    "status": "Broken",
    "active": true,
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "time": 1569340547109,
    "_at": 1569340835269,
    "success": true
}

Deleting an object

To delete an object, you must send an HTTP request DELETE /api/v1/objects/:id with its identifier. In response, the server will receive the configuration of the object and the result of the request.

Request

DELETE /api/v1/objects/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

{
    "id": "someID3458374",
    "name": "Object 03",
    "model": "5d8a3319d0025e0012fba0fa",
    "status": "ok",
    "active": true,
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "time": 1569340547109,
    "_id": "5d8a3c83d0025e0012fbb4ca",
    "success": true
}

Getting object data log

When you receive an object log, you load data packets from the history. At the same time, using two different methods, both several packages and one can be obtained.

You can work with the resource /api/v1/objects/:id/packets as with a list of data packets sent by the object. When using this method, it is recommended to use the begin and end parameters, which indicate the lower and upper boundary of the time interval. Don’t forget that time limits can be set either in Unix Timestamp format (in milliseconds) or in ISO 8601 format (YYYY-MM-DDThh: mm).

Request

GET api/v1/objects/5a718f4543af42110079e8a4/packets?begin=1569326400000&end=1569351600000 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

[
    {
        "_id": "5d8a0547bada12100036a26f",
        "_ts": 1569326407527500,
        "lx": 5,
        "ly": -58,
        "lz": 846,
        "humidity": 18.85,
        "temperature": 29.37,
        "faringate": 28.17,
        "online": true,
        "time": 1569326407527
    }
]

To get one data packet, you need to send a request GET /api/v1/objects/:id/packets/:packetID with the identification number of the packet whose data you want to download.

Request

GET /api/v1/objects/:id/packets/:packetID HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

{
    "_id": "5d8a0547bada12100036a26f",
    "_ts": 1569329888806500,
    "lx": 8,
    "ly": -79,
    "lz": 785,
    "humidity": 19.36,
    "temperature": 29.27,
    "faringate": 28.17,
    "online": true,
    "time": 1569329888806
}

Sending commands

A command is sent from the platform to the device through a  POST /objects/:id/commands/:command request. In this request, instead of :id , the identification number of the object is indicated, instead of :command – the name of the command to be sent. In the body of the request, the parameters and their values are required to complete the command.

Request 

POST /objects/:id/commands/:command HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{
  "param1": "value1",
  "param2": "value2"
}

Response

HTTP/1.1 200 OK
Content-Length: ~

{
  "success": true
}

WebSocket events

Object-packet event

The event occurs when a new packet arrives from the device. The format of the package is similar to the previously described.

Object-update event

The event occurs when one of the fields of the monitoring object is updated.

interface ObjectUpdateMessage {
  id     : String; /* Object id */
  before : Object; /* Set of fields before change */
  after  : Object; /* Set of fields after change */
}

Example

{
  id: "55cefff8e803589a52ec11d0", 
  before: {name: "object name"}, 
  after: {name: "new object name"}
}