Introduction à l’API Ermeo

Ermeo : Comprendre et utiliser l'API
1. Prérequis
2. Bases de l'API
3. Commencer à travailler avec l'API
4. Bonnes pratiques et conseils

Voici la traduction en français :

Ermeo : Comprendre et utiliser l'API

Ermeo est composé de deux produits : la plateforme et l'application. La toute première chose à comprendre au sujet de l'API Ermeo est que cette plateforme et cette application sont entièrement basées sur cette API. Cela signifie que la plateforme et l'application ne sont pas directement connectées, mais utilisent cette API pour échanger des données stockées dans une base de données.

Ainsi, l'API agit comme l'interface entre vous (via l'application ou la plateforme) et les données auxquelles vous avez accès. L'API utilisée par la plateforme et l'application est la même que celle à laquelle nous donnons accès à nos clients. Par conséquent, si vous vous demandez :

Puis-je faire cela avec l'API ?

et que la plateforme et l'application peuvent déjà le faire, vous pourrez le faire grâce à l'API.

1. Prérequis

Quelques éléments sont nécessaires pour commencer à travailler avec notre API :

Le plus évident est d'avoir un minimum de compétences techniques, ou au moins de savoir ce qu'est une API et d'avoir déjà travaillé avec.
Comprendre les bases d'Ermeo. Des formations sont fournies par notre équipe. Si vous n'avez pas été formé ou ne connaissez rien d'Ermeo, veuillez demander ces formations pour éviter une perte de temps lors du développement de vos connecteurs.
Consultez notre documentation API.
Un environnement de test. En général, il est très mauvais de tester une API sur un environnement de production. C'est pourquoi nous pouvons vous fournir un environnement de test, où vous pouvez tester tout ce dont vous avez besoin avant de commencer à travailler sur vos connecteurs. Veuillez noter que ces environnements ne sont en rien comparables à l'environnement de production en termes de performance. Ils sont uniquement destinés aux tests.

2. Bases de l'API

Comme nous l'avons vu précédemment dans cet article, la plateforme et l'application utilisent uniquement notre API pour fonctionner. Cela signifie que toutes les entités (actifs, utilisateurs, interventions, etc.) sont accessibles via notre API. Chacune de ces entités dispose de ses propres routes CRUD (Create, Read, Update, Delete). Dans Ermeo, la plupart des principales entités ont les routes suivantes :

GET /entities permet d'accéder à tous les éléments correspondant à l'entité que vous souhaitez récupérer. Par exemple : GET /assets renverra tous les actifs auxquels vous avez accès.
GET /entities/{id} permet d'accéder à un élément spécifique correspondant à l'entité que vous souhaitez récupérer. Par exemple, GET /assets/1247d918-3cd5-476d-a432-88273e3173d5 récupérera un actif spécifique.
POST /entities/search permet de rechercher une liste d'éléments correspondant à l'entité que vous souhaitez récupérer. Le fait que cette requête soit un POST vous permet de passer un filtre dans le corps de la requête. Par exemple, POST /assets/search renverra tous les actifs selon le filtre que vous avez envoyé dans le corps de la requête.
PUT /entities/{id} permet de mettre à jour un élément spécifique correspondant à l'entité que vous souhaitez mettre à jour. Par exemple, PUT /assets/1247d918-3cd5-476d-a432-88273e3173d5 mettra à jour cet actif spécifique en fonction des informations que vous avez envoyées dans le corps de la requête.
DELETE /entities/{id} permet de supprimer un élément spécifique correspondant à l'entité que vous souhaitez supprimer. Par exemple, DELETE /assets/1247d918-3cd5-476d-a432-88273e3173d5 supprimera cet actif spécifique.

Ces requêtes sont des exemples de ce que vous pouvez faire avec l'API Ermeo. Bien sûr, d'autres requêtes sont également fournies en fonction du type d'entité avec laquelle vous souhaitez travailler. Tout ce que vous devez savoir est listé dans la documentation de l'API.

Un système d'authentification est en place pour sécuriser les requêtes et les données que vous recevez et envoyez. En effet, chaque requête doit être authentifiée pour recevoir une réponse de l'API. Veuillez suivre cet article pour en savoir plus sur la façon d'authentifier vos requêtes.

3. Commencer à travailler avec l'API

Comme mentionné précédemment dans cet article, la toute première chose dont vous avez besoin est un environnement de test. Celui-ci vous sera fourni avec un client_id et un client_secret, utilisés pour créer un jeton d'accès qui sera nécessaire pour authentifier vos requêtes.

Une fois que vous avez cet environnement, vous êtes prêt à commencer. Avant de développer quoi que ce soit, nous vous recommandons d'utiliser Postman pour vous familiariser avec notre API en testant quelques routes listées dans la documentation de l'API.

Postman est un outil disponible sur Windows, Mac et Linux utilisé pour consommer des API, qui peut être téléchargé ici. Une fois téléchargé, vous pouvez lancer l'outil. Lors de l'ouverture de Postman, vous serez invité à vous connecter ou à créer un compte. Si vous souhaitez passer cette étape, vous pouvez :

Vous devriez maintenant arriver sur l'écran principal de Postman. À partir de là, vous pouvez commencer à créer une nouvelle collection et de nouvelles requêtes.

Si vous avez consulté la documentation de l'API, vous remarquez qu'elle est divisée en 7 parties :

Nous recommandons d'importer chacune de ces parties dans Postman, afin d'avoir accès à toutes les requêtes nécessaires directement préconfigurées. Pour ce faire, pour chaque partie, cliquez sur "Exporter les références groupées" :

Cela devrait ouvrir une nouvelle page contenant du texte au format YAML. Copiez l'URL de cette page. Dans Postman, cliquez sur le bouton Importer :

Sélectionnez "Lien", collez le lien de la documentation de l'API que vous avez copié précédemment et cliquez sur Continuer :

Enfin, cliquez sur Importer :

Vous devriez maintenant avoir accès à toutes les requêtes d'une partie dans une collection Postman et commencer à les utiliser :

![Requêtes Postman](https://support.causeway.com/servlet/rtaImage?eid=ka0P30000000Q0v&feoid=00N4K000003

5VJF&refid=0EM4K000002smxc)

Une fois que vous avez importé toutes les parties de la documentation de l'API, vous êtes prêt à commencer à travailler avec l'API Ermeo !

Il existe bien sûr de nombreuses façons de travailler avec notre API et de nombreux outils sont disponibles sur Internet pour cela. Comme concurrent direct de Postman, nous avons Insomnia, un client API open-source disponible en téléchargement ici.

Nous pouvons également travailler avec des outils ETL (Extract, Transform, Load), les plus célèbres étant :

Bien sûr, l'autre possibilité est de développer vos propres connecteurs à partir de zéro en utilisant la technologie de votre choix (JavaScript, PHP, .NET ou tout autre langage ou framework que vous souhaitez).

4. Bonnes pratiques et conseils

4.1. Lisez tous les articles de cette section

Une fois que vous vous serez familiarisé avec les différentes routes de notre API, vous commencerez à réfléchir au workflow que vous souhaitez construire. Avant d'aller plus loin, veuillez lire les articles suivants, ils peuvent vous aider énormément car ils couvrent la plupart des cas d'utilisation de nos clients en matière d'intégrations API :

4.2. Ne pas envoyer plusieurs requêtes en même temps

Lors de la création de votre connecteur dans un environnement de test, gardez à l'esprit que cet environnement est plus lent que l'environnement de production. C'est pourquoi le temps d'exécution de votre connecteur sera beaucoup plus rapide une fois déployé sur votre espace de travail en production. Ne pas envoyer plusieurs requêtes en même temps, et attendez toujours que l'API réponde avant de continuer votre workflow. Cela vous permettra d'économiser des ressources, tant de votre côté que du nôtre.

4.3. Utilisez le réseau de votre navigateur lors de la navigation sur la plateforme

Notre documentation API est très complète en ce qui concerne l'utilisation de chacune des routes accessibles avec notre API. Mais il n'y a pas de meilleure aide que de voir toutes les requêtes envoyées par la plateforme à notre API. Pour cela, allez sur la plateforme Ermeo, faites un clic droit n'importe où sur une page et sélectionnez Inspecter. Une fois fait, sélectionnez l'onglet Réseau, puis sélectionnez Fetch/XHR et enfin filtrez toutes les requêtes SVG faites à notre API en entrant -.svg dans le champ de filtrage :

Ensuite, en naviguant sur la plateforme, vous verrez toutes les requêtes envoyées à notre API. Rappelez-vous que cette API est la même que celle que vous pouvez utiliser ! N'hésitez donc pas à les consulter, à voir les corps des requêtes, les en-têtes et les paramètres ainsi que les réponses de l'API.

N'hésitez pas à me demander si vous avez besoin de plus de précisions ou d'assistance supplémentaire !