Introduction à l'API (REST API)
Préambule
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).
Utilisation
Environnements et URL d'accès
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.
Bac à sable (sandbox)
C'est l'environnement dédié aux tests. Vous pouvez y faire des essais de requêtes, sans peur d'impacter vos données réelles.
Format 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.
- ISO-8601 , par exemple
2017-07-21T08:55:00+01:00 - Unix timestamps (milliseconds) , par exemple
1500627300905
Format de date ISO-8601
IntentPlatform utilise des dates au format ISO-8601
Pour information :
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.
Emettre une requête sur l'API
Pour construire votre requête, il faut concaténer l'url de base et le chemin d'accès.
Par exemple, ci-dessous pour l'API Assets v1.0 une requête POST s'écrit :
- environnement sandbox : https://apisandbox.hubintent.com/api/assets/v1/assets
- environnement production : https://api.hubintent.com/api/assets/v1/assets
Cette fois-ci, pour l'API Users v1.0 une requête GET s'écrit :
- environnement sandbox : https://apisandbox.hubintent.com/api/users/v1/users
- environnement production : https://api.hubintent.com/api/users/v1/users
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 :
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
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.
Mises à jour - Rétro-compatibilité
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.