Exploitation des Web Services
La plateforme IoT magic Builder expose des API REST permettant d'interagir avec vos équipements et leurs données de manière programmatique. Ces web services sont essentiels pour :
- Intégrer vos données dans des systèmes tiers (ERP, outils de BI, applications métier)
- Automatiser des traitements en connectant la plateforme à vos workflows existants
- Développer des applications exploitant les données de vos équipements IoT
- Orchestrer des processus métier en temps réel avec vos données
Grâce aux API mises à disposition, vous pouvez interroger la liste des équipements disponibles, extraire les données collectées et piloter vos objets connectés selon vos besoins.
Endpoints disponibles
URL de base
Tous les appels vers les web services de la plateforme IoT magic Builder doivent être effectués sur l'URL suivante :
https://api.magicbuilder.io/
Documentation Swagger
L'ensemble des endpoints disponibles est documenté dans notre Swagger. Vous y trouverez :
- La liste complète des endpoints disponibles
- Les paramètres attendus pour chaque requête
- Les formats de réponse
- La possibilité de tester les appels directement depuis l'interface
Accéder à la documentation Swagger
Création d'accès API
Pour exploiter les web services de la plateforme, vous devez créer une application qui vous fournira les identifiants nécessaires à l'authentification.
Prérequis
Avant de commencer, assurez-vous de disposer :
- D'un compte utilisateur valide sur la plateforme
- Des permissions nécessaires pour réaliser les actions souhaitées
Accéder à la gestion des applications
- Connectez-vous à la plateforme avec vos identifiants
- Dans le menu en haut à droite, accédez à Mon profil
- Cliquez sur l'onglet Mes applications
Créer une nouvelle application
- Cliquez sur Ajouter une application dans le panneau de gauche
- Remplissez les informations générales :
- Label : Donnez un nom explicite à votre application
- ID de l'application : Définissez un identifiant unique (ex:
mon-application-api)
- Configurez les Accès & Restrictions :
- Tous : L'application aura accès à vos comptes entreprise
- Seulement... : Sélectionnez les comptes d'entreprise spécifiques auxquels l'application pourra accéder
- Définissez les Permissions :
- Lecture seule : L'application peut uniquement consulter les données via les API
- Lecture et écriture : L'application peut consulter et modifier les données
- Cliquez sur Enregistrer pour créer l'application
Récupérer les identifiants de l'application
Une fois l'application créée, une fenêtre de confirmation s'affiche avec les identifiants :
- ID de l'application : Identifiant à utiliser pour l'authentification OAuth
- Clé secrète de l'application : Clé secrète à conserver précieusement et à fournir couplée à l'ID
La clé secrète ne sera plus visible après la fermeture de cette fenêtre. Copiez-la immédiatement et conservez-la dans un endroit sécurisé. En cas de perte, vous devrez créer une nouvelle application.
Enregistrer ces informations dans un endroit sécurisé, puis cliquez sur Fermer.
Votre application apparaît désormais dans la liste Mes applications avec son label, son ID et sa date de création.
Authentification
L'API utilise le protocole OAuth 2.0 pour sécuriser l'accès aux ressources. L'authentification combine les identifiants de votre application avec vos credentials utilisateur pour obtenir un token d'accès.
L'authentification s'effectue en deux étapes :
- Obtention du token : Identifiants de votre application (client ID et client secret) ainsi que vos credentials utilisateur (username et password) au serveur d'authentification
- Utilisation du token : Utilisation du token dans l'en-tête de chaque requête API
Obtenir un token d'accès
Pour obtenir un token, effectuez une requête POST vers l'endpoint d'authentification :
POST https://hello.magicbuilder.io/realms/master/protocol/openid-connect/token
Paramètres de la requête
| Paramètre | Type | Description |
|---|---|---|
grant_type | string | Doit être password |
client_id | string | L'ID de votre application |
client_secret | string | La clé secrète de votre application |
username | string | Votre identifiant utilisateur (adresse email) |
password | string | Votre mot de passe utilisateur |
Si votre mot de passe ou votre identifiant contient des caractères spéciaux, pensez à les encoder en URL (percent-encoding) avant l'envoi.
Exemple avec cURL
curl -X POST "https://hello.magicbuilder.io/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=mon-application-api" \
-d "client_secret=votre-cle-secrete" \
-d "username=utilisateur@example.com" \
-d "password=votre-mot-de-passe"
Réponse
En cas de succès, vous recevez une réponse JSON contenant le token :
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 300,
"token_type": "Bearer"
}
| Champ | Description |
|---|---|
access_token | Le token à utiliser pour les appels API |
expires_in | Durée de validité du token en secondes |
token_type | Type de token (toujours Bearer) |
Utiliser le token dans les requêtes API
Une fois le token obtenu, incluez-le dans l'en-tête Authorization de chaque requête vers l'API :
curl -X GET "https://api.magicbuilder.io/api/v2/current-user" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
Gestion de l'expiration du token
Le token a une durée de validité limitée (indiquée par expires_in). Lorsque le token expire, les requêtes API retournent une erreur 401 Unauthorized. Vous devez alors obtenir un nouveau token en répétant la procédure d'authentification.
Conservez le token en mémoire et renouvelez-le avant son expiration plutôt que d'en demander un nouveau à chaque requête. Cela améliore les performances de votre application.
