Models

Working with models can be carried out not only in the graphical interface of the platform, but also through the use of the API. There is a certain set of basic HTTP requests, the use of which can allow external systems to perform key operations for interacting with models, their parameters and structure. Among these operations:

1. Getting a list of models;
2. Getting information about one model;
3. Creating a new model;
4. Model editing;
5. Deleting a model.

Getting a list of models

In order to get a complete list of models available to the user, you need to send a request GET /api/v1/models. The response will provide an array of objects, each of which is a configuration of a single model.

Request

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

Response

HTTP/1.1 200 OK

[
    {
        "_id": "5d8a1ef2d0025e0012fb76c6",
        "name": "Мodel 01",
        "base": "mqtt",
        "props": {
            "bots": true,
            "hardwareEvents": false,
            "helper": {
                "nostate": "@ric-docs/docs/helpers/mqtt.md"
            },
            "prefix": "",
            "order": 1,
            "defaultNode": "temperature",
            "protocol": "mqtt",
            "idPattern": "mqtt-$tagname-$nanoid",
            "auth": {
                "title": "mqtt_auth",
                "fields": {
                    "username": {
                        "title": "mqtt_username"
                    },
                    "password": {
                        "secret": true,
                        "title": "mqtt_password"
                    }
                }
            },
            "x509": {
                "enabled": true
            }
        },
        "disabled": [],
        "removed": []
    }
]

Getting information about one model

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

Request

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

Response

HTTP/1.1 200 OK

{
    "_id": "5d8a1ef2d0025e0012fb76c6",
    "name": "Model 01",
    "base": "mqtt",
    "props": {
        ...
        },
        "x509": {
            "enabled": true
        }
    },
    "disabled": [],
    "removed": [],
    "success": true
}

Creating a new model

When sending this request, it is worth considering that the model will be created on the basis of those parameters that are specified in the request body. In the example below, only those fields are specified that are required for the model.

In order to build some structure of the model and add several parameters to it, it is necessary to register this structure in the request body or send a new request (see the next paragraph). It is worth noting that when creating the model, external software modules are added automatically. You can verify this by opening the “Code” tab in the created model and viewing its structure.

Request

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

{
  "base": "mqtt",
  "name": "Model 02",
  "description": "Model of microcontroller"
}

Response

HTTP/1.1 200 OK

{
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569334251811,
    "_id": "5d8a23ebd0025e0012fb8103",
    "success": true
}

Model editing

The PATCH method is used to change entities. For models, it can be used as follows.

For example, using the request PATCH api/v1/models/:id the structure of the model can be built taking into account the addition of the necessary parameters and indicating hierarchical relationships. The structure must be specified in the data field in curly brackets. It is registered by analogy with the structure of the model given in the “Code” tab, in the “Models” menu.

In response to the request, all that information about the model and its structure, which was specified in the request body, is indicated.

Request

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

{
  "data": {
    "id": "root",
    "name": "MQTT",
    "active": true,
    "type": "subsystem",
    "children": [
      {
          "id": "external-software-modules",
          "active": true,
          "copy": true,
          "type": "subsystem",
          "children": [],
          "name": "External software modules"
        },
        {
          "id": "params",
          "name": "Params",
          "active": true,
          "type": "subsystem",
          "children": [
          {
                "id": "temperature",
                 "name": "Temperature",
                 "active": true,
                 "type": "argument",
                 "source": "state",
                 "dataType": "number",
                 "unit": "temperature-celsius",
                 "reference": "base/state/temperature",
                "factor": 1,
                 "linear": true
            },
          {
            "id": "humidity",
                "name": "Humidity",
                "active": true,
                "type": "argument",
                "source": "state",
                "dataType": "number",
                "unit": "percent",
                "reference": "base/state/humidity",
            "factor": 1
          }
        ]
        }
    ]
  },
  "base": "mqtt"
}

Response

HTTP/1.1 200 OK

{
    "_id": "5d8a3319d0025e0012fba0fa",
    "base": "mqtt",
    "name": "Model 05",
    "description": "",
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569338137927,
    "_at": 1569338195770,
    "data": {
        "active": true,
        "children": [
            {
            ...   
            }
        ],
        "id": "root",
        "name": "MQTT",
        "type": "subsystem"
    },
    "success": true
}

Deleting a model

To delete a model, you must send a request DELETE /api/v1/models/:id with its identifier. The response will display the main fields of the model and the result of the request.

Request

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

Response

HTTP/1.1 200 OK

{
    "_id": "5d8a23ebd0025e0012fb8103",
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569334251811,
    "success": true
}