<commit_before># IoT Agent API

The **IoT Agent node library** offers a simple REST API which provides common functionality to access, provision and
decommission devices.

## About API

A GET request to the `/iot/about` path, will return a payload similar to the following:

```json
{
    "libVersion": "2.7.0",
    "port": "4041",
    "baseRoot": "/",
    "version": "1.7.0"
}
```

the `version` field will be read from the `iotaVersion` field of the config, if it exists. It can be used as a heartbeat
operation to check the health of the IoT Agent if required.

## Service Group API

For some services, there will be no need to provision individual devices, but it will make more sense to provision
different service groups, each of one mapped to a different type of entity in the context broker. How the type of entity
is assigned to a device will depend on the Southbound technology (e.g.: path, port, APIKey...). Once the device has an
assigned type, its configuration values can be extracted from those of the type.

The IoT Agents provide two means to define those service groups:

-   Static **Type Configuration**: configuring the `ngsi.types` attribute within the `config.js` file.
-   Dynamic **Configuration API**: making use of the API URLs in the configuration URI, `/iot/services`. Please, note
    that the configuration API manage servers under a URL that requires the `server.name` parameter to be set (the name
    of the IoT Agent we are using). If no name is configured `default` is taken as the default one.

Both approaches provide the same configuration information for the types and end up in the same configuration
collection, they are described in the sections below.

The following sections show the available operations for the Configuration API. Every operation in the API require the
`fiware-service` and `fiware-servicepath` to be defined; the operations are performed in the scope of those headers. For
the list case, the special wildcard servicepath can be specified, `/*`. In this case, the operation applies to all the
subservices of the service given by the `fiware-service` header.

For every service group, the pair (resource, apikey) _must_ be unique (as it is used to identify which group to assign
to which device). Those operations of the API targeting specific resources will need the use of the `resource` and
`apikey` parameters to select the appropriate instance.

Note that there is a 1:1 correspondence between payload fields and DB fields (but with some changes in the attribute
naming; e.g.: subservice -> service_path).

### Type Configuration

The IoT Agent can be configured to expect certain kinds of devices, with preconfigured sets of attributes, service
information, security information and other attributes. The `types` attribute of the configuration is a map, where the
key is the type name and the value is an object containing all the type information. Each type can has the following
information configured:

-   **service**: service of the devices of this type.
-   **subservice**: subservice of the devices of this type.
-   **attributes**: list of active attributes of the device. For each attribute, its `name` and `type` must be provided,
    additional `metadata` is optional.
-   **lazy**: list of lazy attributes of the device. For each attribute, its `name` and `type` must be provided.
-   **commands**: list of commands attributes of the device. For each attribute, its `name` and `type` must be provided.
-   **internalAttributes**: optional section with free format, to allow specific IoT Agents to store information along
    with the devices in the Device Registry.
-   **staticAttributes**: this array of attributes will be added to every entity of this type 'as is'. `name` and `type`
    must be provided, additional `metadata` is optional.
-   **trust**: trust token to use for secured access to the Context Broker for this type of devices (optional; only
    needed for secured scenarios). Trust tokens may be called `access_tokens` by some Oauth2 providers.
-   **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific
    types of devices.

### Service Group Model

The table below shows the information held in the service group provisioning resource. The table also contains the
correspondence between the API resource fields and the same fields in the database model.

| Payload Field                  | DB Field                       | Definition                                                                                                                                                                                                                                                                |
| ------------------------------ | ------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `service`                      | `service`                      | Service of the devices of this type                                                                                                                                                                                                                                       |
| `subservice`                   | `subservice`                   | Subservice of the devices of this type.                                                                                                                                                                                                                                   |
| `resource`                     | `resource`                     | string representing the Southbound resource that will be used to assign a type to a device (e.g.: pathname in the southbound port).                                                                                                                                       |
| `apikey`                       | `apikey`                       | API Key string.                                                                                                                                                                                                                                                           |
| `timestamp`                    | `timestamp`                    | Optional flag about whether or not to add the `TimeInstant` attribute to the device entity created, as well as a `TimeInstant` metadata to each attribute, with the current timestamp. With NGSI-LD, the Standard `observedAt` property-of-a-property is created instead. | true |
| `entity_type`                  | `entity_type`                  | name of the Entity `type` to assign to the group.                                                                                                                                                                                                                         |
| `trust`                        | `trust`                        | trust token to use for secured access to the Context Broker for this type of devices (optional; only needed for secured scenarios).                                                                                                                                       |
| `cbHost`                       | `cbHost`                       | Context Broker connection information. This options can be used to override the global ones for specific types of devices.                                                                                                                                                |
| `lazy`                         | `lazy`                         | list of common lazy attributes of the device. For each attribute, its `name` and `type` must be provided.                                                                                                                                                                 |
| `commands`                     | `commands`                     | list of common commands attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional.                                                                                                                          |
| `attributes`                   | `attributes`                   | list of common active attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional.                                                                                                                            |
| `static_attributes`            | `staticAttributes`             | this attributes will be added to all the entities of this group 'as is', additional `metadata` is optional.                                                                                                                                                               |
| `internal_attributes`          | `internalAttributes`           | optional section with free format, to allow specific IoT Agents to store information along with the devices in the Device Registry.                                                                                                                                       |
| `expressionLanguage`           | `expresionLanguage`            | optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl. When not set or wrongly set, `legacy` is used as default value.                                                                                      |
| `explicitAttrs`                | `explicitAttrs`                | optional boolean value, to support selective ignore of measures so that IOTA doesn’t progress. If not specified default is `false`. Additionally `explicitAttrs` can be used to define which meassures defined in JSON/JEXL array will be propagated to NGSI interface.   |
|  |
| `ngsiVersion`                  | `ngsiVersion`                  | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. Possible values are: `v2` or `ld`. The default is `v2`. When not running in mixed mode, this field is ignored.                                                           |
| `defaultEntityNameConjunction` | `defaultEntityNameConjunction` | optional string value to set default conjunction string used to compose a default `entity_name` when is not provided at device provisioning time.                                                                                                                         |
| `autoprovision`                | `autoprovision`                | optional boolean: If `false`, autoprovisioned devices (i.e. devices that are not created with an explicit provision operation but when the first measure arrives) are not allowed in this group. Default (in the case of omitting the field) is `true`.                   |

### Service Group Endpoint

The following actions are available under the service group endpoint:

##### POST /iot/services

Creates a set of service groups for the given service and service path. The service and subservice information will
taken from the headers, overwritting any preexisting values.

Body params:

-   `services`: list of service groups to create. Each one adheres to the service group Model.

E.g.:

```json
{
    "services": [
        {
            "resource": "/deviceTest",
            "apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
            "type": "Light",
            "trust": "8970A9078A803H3BL98PINEQRW8342HBAMS",
            "cbHost": "http://orion:1026",
            "commands": [{ "name": "wheel1", "type": "Wheel" }],
            "attributes": [<commit_msg>fix linter<commit_after># IoT Agent API

The **IoT Agent node library** offers a simple REST API which provides common functionality to access, provision and
decommission devices.

## About API

A GET request to the `/iot/about` path, will return a payload similar to the following:

```json
{
    "libVersion": "2.7.0",
    "port": "4041",
    "baseRoot": "/",
    "version": "1.7.0"
}
```

the `version` field will be read from the `iotaVersion` field of the config, if it exists. It can be used as a heartbeat
operation to check the health of the IoT Agent if required.

## Service Group API

For some services, there will be no need to provision individual devices, but it will make more sense to provision
different service groups, each of one mapped to a different type of entity in the context broker. How the type of entity
is assigned to a device will depend on the Southbound technology (e.g.: path, port, APIKey...). Once the device has an
assigned type, its configuration values can be extracted from those of the type.

The IoT Agents provide two means to define those service groups:

-   Static **Type Configuration**: configuring the `ngsi.types` attribute within the `config.js` file.
-   Dynamic **Configuration API**: making use of the API URLs in the configuration URI, `/iot/services`. Please, note
    that the configuration API manage servers under a URL that requires the `server.name` parameter to be set (the name
    of the IoT Agent we are using). If no name is configured `default` is taken as the default one.

Both approaches provide the same configuration information for the types and end up in the same configuration
collection, they are described in the sections below.

The following sections show the available operations for the Configuration API. Every operation in the API require the
`fiware-service` and `fiware-servicepath` to be defined; the operations are performed in the scope of those headers. For
the list case, the special wildcard servicepath can be specified, `/*`. In this case, the operation applies to all the
subservices of the service given by the `fiware-service` header.

For every service group, the pair (resource, apikey) _must_ be unique (as it is used to identify which group to assign
to which device). Those operations of the API targeting specific resources will need the use of the `resource` and
`apikey` parameters to select the appropriate instance.

Note that there is a 1:1 correspondence between payload fields and DB fields (but with some changes in the attribute
naming; e.g.: subservice -> service_path).

### Type Configuration

The IoT Agent can be configured to expect certain kinds of devices, with preconfigured sets of attributes, service
information, security information and other attributes. The `types` attribute of the configuration is a map, where the
key is the type name and the value is an object containing all the type information. Each type can has the following
information configured:

-   **service**: service of the devices of this type.
-   **subservice**: subservice of the devices of this type.
-   **attributes**: list of active attributes of the device. For each attribute, its `name` and `type` must be provided,
    additional `metadata` is optional.
-   **lazy**: list of lazy attributes of the device. For each attribute, its `name` and `type` must be provided.
-   **commands**: list of commands attributes of the device. For each attribute, its `name` and `type` must be provided.
-   **internalAttributes**: optional section with free format, to allow specific IoT Agents to store information along
    with the devices in the Device Registry.
-   **staticAttributes**: this array of attributes will be added to every entity of this type 'as is'. `name` and `type`
    must be provided, additional `metadata` is optional.
-   **trust**: trust token to use for secured access to the Context Broker for this type of devices (optional; only
    needed for secured scenarios). Trust tokens may be called `access_tokens` by some Oauth2 providers.
-   **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific
    types of devices.

### Service Group Model

The table below shows the information held in the service group provisioning resource. The table also contains the
correspondence between the API resource fields and the same fields in the database model.

| Payload Field                  | DB Field                       | Definition                                                                                                                                                                                                                                                                |
| ------------------------------ | ------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `service`                      | `service`                      | Service of the devices of this type                                                                                                                                                                                                                                       |
| `subservice`                   | `subservice`                   | Subservice of the devices of this type.                                                                                                                                                                                                                                   |
| `resource`                     | `resource`                     | string representing the Southbound resource that will be used to assign a type to a device (e.g.: pathname in the southbound port).                                                                                                                                       |
| `apikey`                       | `apikey`                       | API Key string.                                                                                                                                                                                                                                                           |
| `timestamp`                    | `timestamp`                    | Optional flag about whether or not to add the `TimeInstant` attribute to the device entity created, as well as a `TimeInstant` metadata to each attribute, with the current timestamp. With NGSI-LD, the Standard `observedAt` property-of-a-property is created instead. | true |
| `entity_type`                  | `entity_type`                  | name of the Entity `type` to assign to the group.                                                                                                                                                                                                                         |
| `trust`                        | `trust`                        | trust token to use for secured access to the Context Broker for this type of devices (optional; only needed for secured scenarios).                                                                                                                                       |
| `cbHost`                       | `cbHost`                       | Context Broker connection information. This options can be used to override the global ones for specific types of devices.                                                                                                                                                |
| `lazy`                         | `lazy`                         | list of common lazy attributes of the device. For each attribute, its `name` and `type` must be provided.                                                                                                                                                                 |
| `commands`                     | `commands`                     | list of common commands attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional.                                                                                                                          |
| `attributes`                   | `attributes`                   | list of common active attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional.                                                                                                                            |
| `static_attributes`            | `staticAttributes`             | this attributes will be added to all the entities of this group 'as is', additional `metadata` is optional.                                                                                                                                                               |
| `internal_attributes`          | `internalAttributes`           | optional section with free format, to allow specific IoT Agents to store information along with the devices in the Device Registry.                                                                                                                                       |
| `expressionLanguage`           | `expresionLanguage`            | optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl. When not set or wrongly set, `legacy` is used as default value.                                                                                      |
| `explicitAttrs`                | `explicitAttrs`                | optional boolean value, to support selective ignore of measures so that IOTA doesn’t progress. If not specified default is `false`. Additionally `explicitAttrs` can be used to define which meassures defined in JSON/JEXL array will be propagated to NGSI interface.   |
| `ngsiVersion`                  | `ngsiVersion`                  | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. Possible values are: `v2` or `ld`. The default is `v2`. When not running in mixed mode, this field is ignored.                                                           |
| `defaultEntityNameConjunction` | `defaultEntityNameConjunction` | optional string value to set default conjunction string used to compose a default `entity_name` when is not provided at device provisioning time.                                                                                                                         |
| `autoprovision`                | `autoprovision`                | optional boolean: If `false`, autoprovisioned devices (i.e. devices that are not created with an explicit provision operation but when the first measure arrives) are not allowed in this group. Default (in the case of omitting the field) is `true`.                   |

### Service Group Endpoint

The following actions are available under the service group endpoint:

##### POST /iot/services

Creates a set of service groups for the given service and service path. The service and subservice information will
taken from the headers, overwritting any preexisting values.

Body params:

-   `services`: list of service groups to create. Each one adheres to the service group Model.

E.g.:

```json
{
    "services": [
        {
            "resource": "/deviceTest",
            "apikey": "<KEY>",
            "type": "Light",
            "trust": "8970A9078A803H3BL98PINEQRW8342HBAMS",
            "cbHost": "http://orion:1026",
            "commands": [{ "name": "wheel1", "type": "Wheel" }],
            "attributes": [
{'fraction_non_alphanumeric': 0.08175415059533792, 'fraction_numerical': 0.004276370954217676, 'mean_word_length': 1.3178505490234185, 'pattern_counts': {'":': 28, '<': 4, '<?xml version=': 0, '>': 6, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 232, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1108904', 'n_tokens_mistral': 4447, 'n_tokens_neox': 4233, 'n_words': 2361}