====== Development guide ======


Accessing data via an API is possible if the service gives you the authorization. In this chapter, you will learn how to 
  *  create the api key and define the access rights of a user group 
  *  use the APIKey to authenticate user

===== Setting up =====

Access to APIs is subject to authentication and authorisation. 


APIs access rights are defined by creating a [[teammanager:usergroups|user group]] and defining the access right per API.
In the account manager, user groups, create a group and define all apis access rights.

{{:my_user_groups_-_apis.png?nolink|}}



BasicAuth authentication requires an application key and an application secret called api Keys. In the account manager, [[teammanager:settings|settings]], global, there is an entry "API Keys", Click on the “Add ApiKey” button, select the user group to belong to and save. Copy the generated APi Key.


{{:settings_-_apykeys.png?nolink|}}


=== How to get the assets, assets details and asset data ===

This use case shows you the APIs you can use to obtain a list of all the assets in your account, obtain the details of an asset based on its identifier and retrieve data from connected devices.
==== Assets ====


List all assets for the currently logged-in user.

**GET** **ASSETS**
https://report.iotfactory.eu/api/assets?fields=_id&fields=name

**Request headers**

**Basic authentication** involves sending a verified username and password with your request
In the request Headers, the Authorization header passes the API a Base64 encoded string representing your username and password values, appended to the text Basic as follows:

Basic <Base64 encoded <username>:<password> >


**URL Variables**

| path | type | presence | description | default | conforms | allowed | valids | invalids |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| \- | object | optional |  |  |  |  |  |  |
| status | string | optional | List only assets on this state | `"active"` |  |  | `"new"` `"active"` `"archived"` `"all"` | `""` |
| search | string | optional | Global search value |  |  | `""` |  |  |
| sort | string | optional |  | `"timestamp"` |  |  |  | `""` |
| order | string | optional |  | `"desc"` |  |  | `"asc"` `"desc"` | `""` |
| page | number | optional |  | `0` |  |  |  | `null` `null` |
| limit | number | optional |  | `100` |  |  |  | `null` `null` |
| tags | array | optional | Filter on tags |  | `unique` |  |  |  |
| tags \[+0 \] | string | optional |  |  |  |  |  | `""` |
| geoloc | boolean | optional | Only geolocalized assets | `false` |  |  |  |  |
| mainAsset | string | optional | Geoloc filter: Filter on the asset it was in planning. Format: ids |  |  |  |  | `""` |
| site | string | optional | Geoloc filter: Filter on sites it was in planning. Format: ids |  |  |  |  | `""` |
| state | string | optional | Geoloc filter: Came from/Went to the site (only if a site was sent in the query) | `""` |  |  | `""` `"from"` `"to"` |  |
| withPlanningInputs | boolean | optional |  | `false` |  |  |  |  |
| to | date | optional | Geoloc filter: Check in plannings a planning to that date |  |  |  |  |  |
| from | alternatives | ignore |  |  |  |  |  |  |
| fields | array | optional | Return only referenced fields (useless when site is defined) |  | `unique` |  |  |  |
| fields \[+0 \] | string | optional |  |  |  |  |  | `""` |
| group | array | optional | filter: Came from/Went to the group (only if a group was sent in the query |  | `unique` | `""` |  |  |
| lookup | boolean | optional |  | `false` |  |  |  |  |
| onSite | boolean | optional |  |  |  |  |  |  |
===== Asset =====

Get one asset by ID

**GET** **ASSET**
https://report.iotfactory.eu/api/assets/{id}

**Request headers**

**Basic authentication** involves sending a verified username and password with your request
In the request Headers, the Authorization header passes the API a Base64 encoded string representing your username and password values, appended to the text Basic as follows:

Basic <Base64 encoded <username>:<password> >

**URL Params**

| path | type | presence | description | invalids |
| --- | --- | --- | --- | --- |
| \- | object | optional |  |  |
| id | string | required | Identifier of the asset | `""` |

---

**URL Variables**

| path | type | presence | description | default |
| --- | --- | --- | --- | --- |
| \- | object | optional |  |  |
| populateParents | boolean | optional | if true, 'parents' property will be added to the response | `false` |


Get measurements from asset devices

**GET** **ASSET**
https://report.iotfactory.eu/api/assets/{id}/measurements

**URL Params**

| path | type | presence | description | invalids |
| --- | --- | --- | --- | --- |
| \- | object | optional |  |  |
| id | string | required | asset id | `""` |

---

**URL Variables**

| path | type | presence | description | default | conforms | allowed | valids | invalids |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| \- | object | optional |  |  |  |  |  |  |
| before | date ISO8601 YYYY-MM-DDTHH:mm:ss.sssZ  | optional | Return only measurements before this date |  |  |  |  |  |
| after | date ISO8601 YYYY-MM-DDTHH:mm:ss.sssZ| optional | Return only measurements after this date |  |  |  |  |  |
| page | number | optional |  | `0` |  |  |  | `null` `null` |
| limit | number | optional | limit by measurements and smartmeasurements | `100` | `min: 0` |  |  | `null` `null` |
| type | array | optional | Select only measurements of this type |  | `unique` | `""` |  |  |
| device | string | optional | Device id |  |  | `""` |  |  |
| tags | array | optional | Filter by (smart)devices tags |  | `unique` | `""` |  |  |
| step | string | optional | By step |  |  |  | `""` `"quarthourly"` `"hourly"` `"daily"` `"weekly"` `"monthly"` `"yearly"` |  |
| merge | boolean | optional | Merge measurements of same timestamp |  |  |  |  |  |

Devices, smart devices or static lists can be attached to an asset.  The identifiers of these objects can be found in the corresponding table of an asset.


Ex: Get the last ten weekly smart measurements of a smart devices (_id:6513e6769a0d12001268d169) attached to an asset(_id:6508132813019d0012630749) after the 16/11/2023 10pm UTC

      https://report.iotfactory.eu/api/assets/6508132813019d0012630749/measurements?device=6513e6769a0d12001268d169&type=Occupied (first)&step=weekly&limit=10&after=2023-11-16T22:00:00.000Z
      

Result:
      {
    "data": [
        {
            "_id": "65aef1c2d6c621996407a92c",
            "smartdevice": {
                "id": "6513e6769a0d12001268d16c",
                "team": "1ha4pei7n.hp",
                "name": "Desk occupied"
            },
            "timestamp": 1705878000000,
            "updatedAt": "2024-01-23T14:36:18.131Z",
            "device": {},
            "staticList": {},
            "measurements": [
                {
                    "type": "Occupied (first)",
                    "value": 0,
                    "before": 1705878000000,
                    "at": "2024-01-21T22:55:00.000Z",
                    "unit": "",
                    "cache": true
                }
            ]
        },
        
        ...
        
        {
            "_id": "6573242b70f14a87dbaf0079",
            "smartdevice": {
                "id": "6513e6769a0d12001268d16c",
                "team": "1ha4pei7n.hp",
                "name": "Desk occupied"
            },
            "timestamp": 1700434800000,
            "updatedAt": "2023-12-08T14:14:35.531Z",
            "device": {},
            "staticList": {},
            "measurements": [
                {
                    "type": "Occupied (first)",
                    "value": 0,
                    "before": 1700434800000,
                    "at": "2023-11-19T22:55:00.000Z",
                    "unit": "",
                    "cache": false
                }
            ]
        }
    ],
    "pages": 1,
    "parent": {
        "_id": "6508132813019d0012630743",
        "name": "Anderlecht"
    },
    "recordsFiltered": 10
    }