Heatzy openAPI
Utiliser les APIs fournies par heatzy pour contrôler votre pilote
Nous avons mis à jour nos APIs et nous avons rendu disponible les nouvelles APIs pour nos clients. Pour avoir accès aux APIs complètes, vous pouvez utiliser ces liens :
APIs heatzy téléchargeable au format PDF:
https://mega.nz/#F!eupDGQCb!gKu0lXx0VM7gbZxmuTb0DQAPIs heatzy documentées pour Postman :
https://documenter.getpostman.com/view/10809108/SzYXYfP6?version=latestAPIs heatzy documentées sur Swagger :
https://app.swaggerhub.com/apis/Heatzy/heatzy- pilote_api_2020/1.0
Nous avons également décidé de détailler ici quelques fonctions principales de nos nouvelles APIs et de le faire sous forme de tutoriel qui pourra aussi être suivi par des débutants. Donc si vous êtes curieux de savoir comment fonctionne votre pilote, ou que vous souhaitez vous lancer dans un projet Arduino pour contrôler vos équipements à distance, ou tout simplement que vous souhaitez en savoir plus sur nos nouvelles APIs, ce tutoriel est fait pour vous !
Chapitre 1 : les bases
Sommaire :
1/ Télécharger et installer postman
1bis/ Enregistrer un compte heatzy et appairer un pilote
2/ Première requête : S’identifier
3/ Obtenir les informations relatives à votre pilote
1/ Télécharger et installer postman
Si vous avez déjà installé postman, ou si vous êtes déjà familier avec l’utilisation d’APIs et avez vos propres outils, vous pouvez passer à l’étape 1bis.
Postman c’est quoi ?
Postman c’est un logiciel bien pratique développé par Google qui permet d’envoyer des requêtes API (mais pas que). Le logiciel est gratuit et assez populaire, il est donc très utilisé pour tester des APIs rapidement. Vous n’êtes pas obligé de passer par ce logiciel pour utiliser des API, mais si vous débutez dans ce domaine nous vous conseillons de l’installer. Son interface est facile à comprendre et le logiciel est rapide à prendre en main, à condition de connaître quelques mots d’anglais.
Téléchargement et installation
Rendez vous à cette adresse : https://www.postman.com/downloads/ pour télécharger postman (disponible pour windows, mac et linux). L’installation est plutôt simple donc laissez-vous guider. Quand vous aurez fini d’installer, ouvrez postman et vous devriez vous retrouver avec ceci :
1bis/ Enregistrer un compte heatzy et appairer un pilote
Vous pouvez utiliser votre compte personnel ou créer un nouveau compte pour tester les APIs. Pour se faire, vous pouvez suivre ce lien : www.heatzy.com/blablablabla
Si vous avez déjà vos identifiants et un pilote appairé à votre compte, vous pouvez passer à l’étape suivante.
2/ Première requête : S’identifier
Avant de commencer :
Avant d’envoyer notre première requête il est important de comprendre le fonctionnement d’une API. Pour faire simple, c’est une méthode qui permet d’envoyer des messages à un serveur (en l’occurrence le serveur utilisé par Heatzy). Ces messages peuvent avoir plusieurs fonctions différentes : envoyer un ordre, demander des informations, mettre à jour des informations, supprimer ou créer des données.
Heatzy n’est pas la seule entreprise à utiliser des APIs. En réalité, presque toutes les entreprises proposant des services utilisant internet ont leurs propres API. Pour rendre leur fonctionnement plus simple, les API suivent un protocole qui est quasiment le même pour l’envoi de requête. On distingue donc (la plupart du temps) quatre types de requête différents :
GET : pour demander une information au serveur
POST : pour envoyer une nouvelle information au serveur
PUT : pour mettre à jour ou modifier une information déjà sur le serveur
DELETE : pour supprimer des données présentes sur le serveur
Pour résumer, le système API est un protocole qui sert à communiquer avec un service sur le web. Ces APIs peuvent être utilisées par des entreprises ou des particuliers pour beaucoup de raisons différentes. Les API partagées par Heatzy sont à destination de nos clients pour qu’ils puissent interagir avec nos produits en dehors de l’application heatzy et proposer des solutions créatives ou des usages détournés du produit heatzy pilote.
Première requête à envoyer
Pour éviter que n’importe qui puisse mettre à jour les données présentes sur nos serveurs, la première étape à effectuer est de s’identifier. Une fois identifié, le serveur saura quel utilisateur envoie des demandes et pourra répondre en fonction.
Commencez d’abord par créer une nouvelle collection dans postman. On pourra la nommer « heatzy_pilote » par exemple, mais vous pouvez choisir le nom qui vous plait.
Ensuite on va créer la première requête à envoyer au serveur. Cette requête sert à nous identifier au près du serveur et se fait en deux étapes :
Envoi de la requête au serveur en indiquant le nom du compte ainsi que le mot de passe.
Réponse du serveur qui nous donne un ticket unique qui nous servira de « carte d’identité » valable pendant une semaine.
Attention maintenant on rentre dans la partie technique, en comprenant bien le fonctionnement de cette première requête vous ne devriez pas avoir de mal pour la suite du tutoriel.
Pour être sûr que le message arrive jusqu’au serveur, il faut indiquer son « adresse » comme si on envoyait un courrier. Ici, le serveur est connecté à internet, son adresse est donc une adresse web. C’est ce qu’on appelle l’URL. Ici on envoie donc une requête POST à l’URL suivante : http://euapi.gizwits.com/app/login
http://euapi.gizwits.com, c’est la partie « fixe » de l’adresse. app/login c’est le complément d’adresse spécifique à un service (l’identification du compte dans le cas présent)
Ensuite, il faut remplir la requête, comme avec un courrier, on ne peut pas envoyer une enveloppe vide. Donc pour communiquer au serveur il faut donner certaines informations.
La première c’est l’identifiant de l’application heatzy : X-Gizwits-Application-Id. Cela sert à dire au serveur que l’on souhaite utiliser les services de heatzy.
L’identifiant de l’application pour heatzy est : c70a66ff039d41b4a220e198b0fcc8b3. Il faut renseigner ces informations dans la partie Headers
Enfin, il faut donner ses informations personnelles au serveur pour qu’il puisse nous reconnaître. Ces données sont en quelque sorte le message du courrier. Ces données se retrouvent donc dans la partie Body sous la forme suivante :
Veillez à bien cocher la case raw, ensuite vous pourrez écrire ceci :
{
"username": "adresse-client@exemple.fr",
"password": "mot-de-passe-compte"
}
Après username, écrivez entre guillemets l’adresse mail de votre compte heatzy. Après password, écrivez entre guillements le mot de passe de votre compte heatzy.
Dernière vérification, vous pouvez visualiser votre requête sous forme de code. Si vous avez suivi toutes les instructions sans erreur vous devriez voir ceci :
Vous pouvez terminer en cliquant sur Send. Votre requête sera envoyée au serveur, et s’il n’y a pas d’erreur vous obtiendrez une réponse comme celle-ci :
La variable token va vous servir de carte d’identité pour utiliser les API. Elle vous sera demandée pour la plupart des requêtes. Cette valeur change au bout d’une semaine.
3/ Obtenir les informations relatives à votre compte
La requête à envoyer
Maintenant que vous avez votre ticket utilisateur vous aller pouvoir commencer à expérimenter avec nos APIs. Vous pouvez commencer par envoyer une requête pour obtenir des informations sur votre compte.
Cette requête est plutôt simple, il s’agit d’une requête GET vers l’adresse suivante :
https://euapi.gizwits.com/app/bindings?limit=20&skip=0
Créez une nouvelle requête dans votre collection heatzy et renseignez les paramètres suivants dans Headers
X-Gizwits-Application-Id : c70a66ff039d41b4a220e198b0fcc8b3
X-Gizwits-User-token : le ticket utilisateur obtenu précédemment
Après avoir envoyé la requête on obtient normalement une réponse du serveur qui ressemble à ça :
Si jamais vous avez une réponse comme celle-ci, il est normal que vous trouviez ça illisible tel quel. On va donc cliquer sur la case Pretty et indiquer que l’on visualise du JSON
Toutes les informations ici ne sont pas à utiliser. On va se concentrer sur les plus importantes pour nous:
dev_alias : c’est le nom du produit affiché dans l’application
product_name : c’est le type de produit (ici c’est un heatzy pilote)
mac : l’adresse mac du produit qui peut vous être utile pour d’autres requêtes API
did : l’identifiant de l’appareil qui peut vous être utile pour d’autre requêtes API
is_online : permet de vérifier si le produit est bien connecté au serveur
Si vous plusieurs produits Heatzy, vous retrouverez ces données pour tous les produits appairés à votre compte.
Conclusion
Si vous êtes venu à bout de ce tutoriel, félicitations ! Vous avez fait le plus compliqué, et vous avez maintenant compris comment envoyer des requêtes API pour échanger des informations avec notre serveur.
Dans un prochain tutoriel nous verrons comment communiquer directement avec les appareils Heatzy pilotes appairés à votre compte.
Chapitre 2 : envoyer des ordres
Récap :
Dans le chapitre précédent, on a vu comment s’identifier auprès du serveur à l’aide d’une requête POST et comment demander des informations sur nos appareils à l’aide d’une requête GET. À présent, nous allons voir comment envoyer des ordres à un pilote.
Sommaire :
1/ Avant de commencer
2/Envoi de l’ordre
1/ Avant de commencer
Retour sur la requête GET app/binding
Dans le chapitre précédent, nous avons envoyé une requête permettant de voir les différents produits Heatzy appairés sur votre compte client. Ces informations sont importantes pour la prochaine requête.
Sélectionner donc un pilote parmi les pilotes connectés au serveur. Vérifier que la valeur is_online renvoie la valeur true. Pour cet exemple, nous choisirons le pilote nommé salon dans l’application, son dev_alias est donc "salon". Enfin vous aller chercher le paramètre did, c’est votre device ID. Ce paramètre est en quelque sorte la « plaque d’immatriculation » du pilote pour le serveur. Chaque pilote a un device ID unique qui lui est approprié et qui sert à l’identifier directement et instantanément par le serveur.
Enfin n’oubliez votre ticket utilisateur (token) que vous avez obtenu lors de votre première requête d’identification.
Les informations à préparer
Avant d’envoyer cette première requête on va s’assurer que vous avez toutes les données qu’il vous faut :
X-Gizwits-Application-Id : c’est l’identifiant de l’application Heatzy.
Pour rappel : c70a66ff039d41b4a220e198b0fcc8b3X-Gizwits-User-token : c’est votre ticket client
did : c’est votre device ID. La plaque d’immatriculation de votre pilote
2/Envoi de l’ordre
Préparation de la requête
On va donc envoyer une requête POST vers l’URL suivante : https://euapi.gizwits.com/app/control/{did}.Mais d’abord on va modifier cette adresse URL pour s’assurer qu’elle fonctionne. On a vu dans le premier chapitre que l’URL c’est l’adresse du serveur. Ici https://euapi.gizwits.com c’est le serveur et/app/control/{did} c’est le « complément d’adresse ». Et dans le complément d’adresse, la valeur {did} devra être remplacé par le device ID de votre pilote.
Par exemple, votre requête POST devra être envoyé à l’URL suivante :https://euapi.gizwits.com/app/control/4ymbiAKoE4RmntLNt5kEFaD, ou 4ymbiAKoE4RmntLNt5kEFaD est le device ID.
Ensuite on prépare le Headers avec l’application ID et votre token.
Quand tout cela est prêt on va pouvoir envoyer notre ordre. Pour ça on va écrire dans la case body et sélectionner raw pour le type de données.
Ecriture de l’ordre
L’envoi d’ordre se fait avec cette commande (à écrire dans le Body) :
Y est un nombre entier qui peut prendre une valeur allant de 1 à 4. Chaque valeur correspond à un mode
1 correspond au mode confort (icône soleil)
2 correspond au mode éco (icône lune)
3 correspond au mode hors-gel (icône flocon)
4 correspond au mode OFF
On va donc envoyer un ordre à notre pilote pour le passer en mode confort. Le code devrait ressembler à ça :
On est prêt à envoyer la requête. Vous pouvez lancer l’app Heatzy sur votre téléphone pour voir le changement d’ordre en direct. Quand votre application est ouverte, envoyez la requête.
Attention : si votre pilote est hors-ligne, vous aurez une réponse du serveur comme ceci :
Si la requête a bien été reçue par le serveur et transféré au pilote, vous devriez avoir une réponse comme celle-ci :
Attention : Si vous envoyez une requête à la mauvaise génération de pilote, le serveur ne vous préviendra pas. Donc vérifiez bien sur l’app que l’ordre a été envoyé.
Et voilà, vous avez réussi à communiquer avec votre appareil sans passer par l’application Heatzy ! Vous pouvez désormais expérimenter et envoyer différents ordres à votre pilote et voir la réaction sur l’application.
Maintenant, vous vous dites peut-être que vous voudriez vous passer entièrement de l’application pour envoyer les ordres et observer l’état de votre pilote en direct. C’est ce qu’on verra dans le prochain chapitre !