API REST
Objectif
L’API REST de l’Iothub permet de realiser des opérations de manipulation des utilisateurs et des logements (realm).
Le contrôle des produits se fait par l’ interface Websocket.
Elle ne permet pas de faire l’installation des produits au sein d’un logement (provisioning) qui reste exclusivement l’apanage de l’application mobile .
L’API permet par exemple :
lister tous les utilisateurs pour un fournisseur donné,
lister tous les realms,
lister tous les produits,
récupérer l’ensemble des informations d’un produit qui appartient à un utilisateur du fournisseur.
Gestions des accès et identités
Il faut disposer d’un compte administrateur pour se connecter à l’interface.
La gestion des identités (CIAM) est fournie par le service AWS Cognito. Ce service assure aussi bien les accès donc des administrateurs sur l’interface web, des clients d’API, que des utiliseurs finaux (endusers).
Listes des routes utiles
Swagger
L’API REST de l’Iothub est disponible ici : https://api.iothub.linkio.net/api-v1/docs/
Voici quelques routes interessantes et les cas d’ausages associés.
Les opérations liées aux utilisateurs
Swagger : https://api.iothub.linkio.net/api-v1/docs/#/EndUsers
Les opérations sur les logements
Swagger : https://api.iothub.linkio.net/api-v1/docs/#/Realm
GET /realms HTTP/1.1
[
{
"id": 162,
"uuid": "e45d6eaf-1617-45a1-be3a-09dd567869bf"
"name": "Ma maison principale",
"timezone": "Europe/Paris",
}
]
Récupérer un realm en particulier :
(on spécifie l’uuid et non l’id)
GET /realms/e45d6eaf-1617-45a1-be3a-09dd567869bf HTTP/1.1
Retour :
{
"id": 162,
"uuid": "e45d6eaf-1617-45a1-be3a-09dd567869bf"
"devices": [
{
"uuid": "2bce7cd0-941c-44be-a667-1a635204d760",
"name": "PASSMAX_639F",
"macBle": "C82CC6D9639F",
"lastHeartbeat": "2024-06-11T13:16:56.000Z",
"ble": "{\"mesh\":{\"provisioned\":1,\"deviceKey\":\"9327B3C1C090B9E05C57D0335779FCAA\",\"unicastAddress\":\"0x0002\"},\"bleMeshRegistration\":0,\"version\":\"0.0.5.1\"}",
"firmware": "0.0.5.1",
"hardware": "6.0.1",
"flashed": false,
"updatedAt": "2024-07-22T15:43:08.000Z",
"alive": false,
"suppliers": [],
"model": {
"id": 124,
"name": "PASSMAX",
"gateway": true,
"manufacturer": {
"id": 14,
"name": "FLEXIMAX"
}
},
"productionOrder": {
"number": 202405212,
"hardware": "6.0.1"
},
"isLastFirmware": true,
"currentHealthStatus": null
},
],
"rooms": [],
"mainGatewayUuid": "2bce7cd0-941c-44be-a667-1a635204d760"
}
Les opérations sur les produits
Swagger : https://api.iothub.linkio.net/api-v1/docs/#/Devices
Pour lister tous les produits d’un fournisseur :
GET /devices/nogateway HTTP/1.1
Pour avoir les infos d’un unique produit :
GET /devices/ccbd8bd9-6468-0000-0000-000000000000 HTTP/1.1
Cela permet de connaître l’état de vie du produit avec la notion de ‘alive’.
Dans le tableau des features, nous pouvons récupérer le dernier état de chaque feature par exemple savoir si une lampe est allumée ou pas.
Historiques sur les features states
Swagger : https://api.iothub.linkio.net/api-v1/docs/#/Features
Historiques sur les métriques
Données brutes d’une feature state
GET /devices/f5456031-4e1f-0000-0000-000000000000/feature/1/null/history?startDate=2024-06-10%2012:29&endDate=2024-06-12%2012:29¤tPage=1&limitPerPage=99999 HTTP/1.1
Avec :
“uuid” (l’uuid du device)
startDate (obligatoire) : date de debut (incluse) de recherche des données de sensor, si renseigné doit obligatoire être au format ISO 8601 (exemple: 2024-03-01T00:00:00Z)
endDate (obligatoire) : date de fin (incluse) de recherche des données de sensor, si renseigné doit obligatoire être au format ISO 8601 (exemple: 2024-03-01T00:00:00Z)
[
{
"value": {
"data": [
{
"name": "present_mode",
"value": 4
},
{
"name": "status",
"value": 0
},
{
"name": "value_type",
"value": 0
},
{
"name": "current_value",
"value": 0
}
]
},
"createdAt": "2024-06-11T12:59:38.648Z"
},
}
]
Données brutes d’une feature sensor selon une date donnée
GET /devices/c15ba067-2e9b-0000-0000-000000000000/feature/1/rel-dev-energy-use-in-a-period-of-day/history?startDate=2024-09-02%2009:16&endDate=2024-09-03%2009:16&calculationType=raw HTTP/1.1
Avec :
“uuid” (l’uuid du device)
startDate (obligatoire) : date de debut (incluse) de recherche des données de sensor, si renseigné doit obligatoire être au format ISO 8601 (exemple: 2024-03-01T00:00:00Z)
endDate (obligatoire) : date de fin (incluse) de recherche des données de sensor, si renseigné doit obligatoire être au format ISO 8601 (exemple: 2024-03-01T00:00:00Z)
- Y ==> present-device-input-power: mesure de puissance
==> erl-data ==> present-input-current: mesure de courant ==> present-input-voltage: mesure de voltage ==> rel-dev-energy-use-in-a-period-of-day : Consommation en W sur une période donnée
calculationType peut valoir average (moyenne), raw (données brutes du réseau), sum (somme des données) (on veut dans le cadre du projet Fleximax)
[
{
"value": {
"data": [
{
"name": "Relative Device Energy Use in a Period of Day",
"unit": null,
"value": 0
}
]
},
"createdAt": "2024-09-03T08:45:15"
},
{
"value": {
"data": [
{
"name": "Relative Device Energy Use in a Period of Day",
"unit": null,
"value": 0
}
]
},
"createdAt": "2024-09-03T09:00:15"
},
{
"value": {
"data": [
{
"name": "Relative Device Energy Use in a Period of Day",
"unit": null,
"value": 0
}
]
},
"createdAt": "2024-09-03T09:15:15"
}
]
Données brutes métiers, regroupées par noms de feature de type sensor du produit
GET /devices/c7948cbf-2833-0000-0000-000000000000/sensor-history?startDate=2024-03-14T05:51:37.708Z&endDate=2024-03-14T13:43:37.708Z HTTP/1.1
Avec :
“uuid” (l’uuid du device)
startDate (facultatif) : date de debut (incluse) de recherche des données de sensor, si renseigné doit obligatoire être au format ISO 8601 (exemple: 2024-03-01T00:00:00Z)
endDate (facultatif) : date de fin (incluse) de recherche des données de sensor, si renseigné doit obligatoire être au format ISO 8601 (exemple: 2024-03-01T00:00:00Z)
[
{
"energy-metering": [
{
"id": 2910739,
"embeddedTimestamp": null,
"createdAt": "2024-03-14T10:02:22.108Z",
"unit": null,
"value": "1234567890123.00",
"index": 14,
"name": "PRM"
},
{
"id": 2910740,
"embeddedTimestamp": null,
"createdAt": "2024-03-14T10:03:08.470Z",
"unit": null,
"value": "112233445566.00",
"index": 14,
"name": "ADS"
},
{
"id": 2910741,
"embeddedTimestamp": "3694933353",
"createdAt": "2024-03-14T10:05:18.265Z",
"unit": "VA",
"value": "6535.00",
"index": 14,
"name": "SINSTS"
},
{
"id": 2910742,
"embeddedTimestamp": "3694933353",
"createdAt": "2024-03-14T10:05:18.275Z",
"unit": "V",
"value": "100.00",
"index": 14,
"name": "URMS"
},
{
"id": 2910743,
"embeddedTimestamp": "1706782953",
"createdAt": "2024-03-14T10:05:43.335Z",
"unit": "VA",
"value": "6535.00",
"index": 14,
"name": "SINSTS"
},
{
"id": 2910744,
"embeddedTimestamp": "1706782953",
"createdAt": "2024-03-14T10:05:43.345Z",
"unit": "V",
"value": "100.00",
"index": 14,
"name": "URMS"
}
]
}
]
}