L’API IntentPlatform se présente sous la forme d'une collection de services web permettant de mettre en place des interactions entre vos applications et IntentPlatform.
Répondant à l'architecture REST, elle s'appuie sur des standards ouverts d'interopérabilité universels comme le protocole de transport HTTP et le format de représentation de données JSON.
Fonctionnalités
L'API couvre l’ensemble des fonctionnalités de la plateforme et permet à ce titre, pour l’ensemble des problématiques de services liées à l’exploitation et à la maintenance d’un patrimoine :
de poster et partager des données (données d’usage, signalement, appel, données d’interventions, etc.) ;
de récupérer les données partagées (toute nature de données échangées sur la plateforme) ;
d’accéder aux signalements, alertes et données des indicateurs définis ;
de déclarer de nouvelles alertes ou de nouvelles demandes d’intervention ;
de créer, modifier, supprimer des éléments de patrimoine (patrimoine hiérarchisé, équipements, locataires) ;
de déclarer, gérer et monitorer des objets connectés (télésurveillances, automates de régulation, VMC connectées, chaudières connectées, domotique, capteurs, compteurs communicants, etc.) ;
d’accéder aux documents associés à un élément du patrimoine ou d’en associer un nouveau.
Sécurité
Les mécanismes de sécurisation des connexions et d’authentification des appels via l’API sont identiques à ceux utilisés dans l’ensemble des outils développés. Cela signifie que tous les appels API sont effectués au nom d’entités préalablement créées et autorisées à accéder à la plateforme, associées à une société titulaire d’un contrat d’exploitation et autorisée par le titulaire à accéder à tout ou partie de son patrimoine.
Via sa connexion à l’API, une entité (bailleur, mainteneur, prestataire, etc.) ne pourra pas accéder à des données situées en dehors de son périmètre, composé des seuls éléments dont elle a soit la propriété ou pour lesquels elle a reçu une autorisation de partage de la part de leur propriétaire, le partage portant en outre les informations sur les autorisations de modification des objets accédés.
Chiffrement
IntentPlatform impose le chiffrement systématique de la couche de transport (standard TLS) pour accéder aux ressources de l’API. De cette manière, l’ensemble des données échangées entre vos applications et IntentPlatform sont chiffrées.
Authentification
Une clé d'API est constitué d'un :
CLIENT_ID (ex : 55555c22-1ff1-4444-a333-4444c1afddb1)
CLIENT_SECRET (ex : 4444b333-f22b-1b22-22f1-ca22e22a1b1d)
Une adresse mail est associée à chaque clé d'API. Elle recevra une synthèse, toutes les 24h, des erreurs rencontrées.
Compte développeur
Contactez Intent Technologies (serviceclient@intent.tech) pour activer votre compte développeur et obtenir votre CLIENT_ID et CLIENT_SECRET.
Autorisation (scopes)
IntentPlatform s’appuie sur OAuth2 pour gérer les permissions d’accès aux API. Le modèle OAuth régit de façon standardisée la négociation d’une autorisation d’accès accordée par un propriétaire de ressources (un tiers souscrit au service) à une application cliente (votre application) accédant à ses ressources via une API (ici l’API IntentPlatform).
Formattage des données
JSON
Les API IntentPlatform utilisent la notation standard JSON pour formatter les données échangées.
Dates et heures
Selon les APIs d'IntentPlatform que vous utiliserez, deux différents formats d'horodatage sont employés. Nous vous conseillons de vous référer aux pages dédiées pour chaque format.
Lorsqu'une date est postée au format : 2017-10-25T02:30:53Z --> alors le Z signifie qu'il s'agit du fuseau horaire UTC
Comme indiqué dans la documentation spécialisée, il est aussi possible d'écrire la date sous la forme : 2017−10−25T02:30:53+01:00
--> ce qui implique un fuseau UTC + 1h00 (soit la France, à l'heure d'hiver)
Cela étant, puisque la grande majorité des utilisateurs IntentPlatform sont en France, nous avons mis en place un mécanisme permettant de lire un format du type 2017-10-25T02:30:53 comme étant une date basée sur le fuseau Central European Time : CET / Paris.
Utilisation
Obtention d'un token d'accès
L'obtention du token d'accès est le pré-requis obligatoire à toute requête. C'est le certificat qui sera utilisée par votre client pour s'authentifier auprès de l'API.
Authentification
URL
https://accountsandbox.hubintent.com/oauth/token
verbe HTTP
POST
En-têtes
En-tête
Valeur
Content-Type
application/x-www-form-urlencoded
Body (x-ww-form-urlencoded)
grant_type
client_credentials
client_id
le CLIENT_ID de votre compte développeur
client_secret
le CLIENT_SECRET de votre compte développeur
Exemple de requête d'obtention de token
Un exemple d'implémentation dans différents langages est disponible ci-dessous:
Pour vous connecter à IntentPlatform, il existe deux URL :
URL d'authentification : s'authentifier et récupérer un jeton d'accès sur l'API
URL de base : URL permettant d'accéder aux ressources et racine de toutes les routes de l'API
Production
ci, les données sont réelles et les requêtes les concernent directement. Il faut donc réserver cet environnement aux codes testés et vérifiés au préalable sur le bac à sable.
Permet de lister, créer, activer un terminal ; Interroger son statut, ses entrées, ses sorties, ses liens objet-flux, ses flux ; déclarer ses entrées, ses sorties, ses paramètres techniques ; Publier des données ou des commandes.
Terminaux
/Users
Permet de créer et manager vos utilisateurs et leurs associer un périmètre géographique de gestion
Identifiant et code d'accès, restriction géographique
Retrouvez toutes nos APIs et les requêtes disponibles sur l'API Reference.
Verbes HTTP
Le verbe HTTP utilisé pour accéder à l’URL indique la fonctionnalité de l’API déclenchée sur l’élément correspondant :
Verbe
Title
GET
Télécharger une représentation de l’élément
PUT
Mettre à jour l’élément
PATCH
Éditer l'élément
POST
Ajouter l'élément
DELETE
Supprimer l'élément
Jeton d'accès
Le jeton d'accès obtenu précédemment devra être transmis à chaque requête à l'aide de l'en-tête suivant :
Authorization : Bearer <votre_jeton_d'accès>
Paramètres
Paramètres de pagination
Il est difficile d’anticiper avec exactitude l’évolution de la quantité de données qui sera retournée lors des différentes requêtes. Nous paginons donc nos ressources.
De plus, la pagination étant une information importante, elle est positionnée dans la requête.
(ex : page=1&perPage=20)
Le code retour HTTP correspondant au retour d’une requête paginée est 200 Ok.
Dans le cas où la pagination demandée ne rentre pas dans les valeurs tolérées par l’API, la réponse HTTP sera un code erreur 400, avec une description explicite de l’erreur dans le body.
Exploiter la pagination
Dans la réponse à votre requête, vous allez trouver un attribut _links vous permettant de parcourir la pagination.
Cet objetcontient un ou plusieurs liens hypermedia, les valeurs possibles étant :
- next: le lien vers la page présentant les résultats suivants
- last: le lien vers la dernière page de résultats
- first: le lien vers la 1ere page de résultats
- prev: le lien vers la page présentant les résultats précédents
Paramètres de tri
Certaines API permettent d'indiquer à l'aide du paramètre sort comment on souhaite trier la liste des résultats de la requête que vous émettez.
Exemple : comment ordonner mon résultat de recherche dans l'ordre chronologique inverse de mes creationDate?
Add a caption...
Paramètres de tri
Il est possible de spécifier une période de temps pour la consultation des données GET. Cette période est limitée à un an par requête.
since : permet de récupérer toutes les données qui ont été modifiées par la plateforme Intent depuis le...
from/to : permet de récupérer toutes les données d'IntentPlatform entre le ... et le ...
Paramètres de temps
Le paramètre fields permet de restreindre les résultats aux seuls attributs qui vous intéressent parmi la liste de tous les attributs disponibles.
Traiter la réponse
Codes de retour HTTP
L'API utilise les codes de retour HTTP classiques, que l'on peut répartir en trois familles :
2xx : Les codes de retour commençant par 2xx sont des codes de retour indiquant que l'opération demandée s'est bien déroulée, ou qu'elle est en cours, sans détection de problème.
4xx : Les codes en 4xx signalent un problème détecté par le client ou portant sur la communication client-serveur.
5xx : Les codes en 5xx signalent un problème interne au serveur.
L’API Intent est mise à jour régulièrement en fonction des ajouts de fonctionnalités et de l’enrichissement technique et fonctionnel d’IntentPlatform. Intent assure cependant l’entière rétro-compatibilité de l’API avec les connecteurs développés.