Comment fonctionne notre API ?

Qu'est ce qu'Ermeo ?

Ermeo est la plateforme de l'opérateur connecté, c'est à dire une solution web et mobile conçue pour digitaliser tout type d'opérations et de documents. Vous permettant ainsi de supprimer l'utilisation du papier ainsi que les tâches à faible valeur ajoutée ralentissant et complexifiant le quotidien des opérateurs terrain.

Pour permettre de récupérer les données de façon automatique, nous fournissons aussi à nos collaborateurs un accès programmatique à leurs données via API (interfaces de programmation d'applications). L'API donne un moyen d’accès aux données de façon réutilisable et standardisée.

Cet article explique comment fonctionne notre API et quelles sont les méthodes pouvant être utilisées. Les autres articles présents dans cette catégorie, permettront de détailler les différentes requêtes pouvant être réalisées.

Une API est un moyen de communication entre deux applications différentes (ou bien deux composantes d'une même application). Elle permet ainsi aux programmes informatiques d'échanger des informations entre eux.

Notre API est une API privée garantissant ainsi la sécurité des données de nos collaborateurs. Seuls les utilisateurs autorisés au sein de votre entreprise, pourront accéder à vos ressources. Une ressource est un objet (équipement, interventions, utilisateurs) contenant des métadonnées. Chaque ressource contient donc des méta-données qui lui sont propres.

L'API d' Ermeo est une API REST (REpresentational State Transfer), constituant ainsi un ensemble de normes qui structurent la façon de communiquer les données entre votre application et Ermeo. 

Ce type d'API présente plusieurs avantages :

• La séparation du client et du serveur, offrant un moyen de communication standardisé entre le client et Ermeo.
• Le fait d’être stateless, rendant chaque réponse et chaque requête déterminée et compréhensible. 
• Le fait d'être cacheable, permettant de diminuer le temps de chargement afin d'avoir des réponses rapides.

Les méthodes utilisables avec notre API

GET

La méthode GET permet de récupérer une ressource unique (en spécifiant son identifiant) ou une liste de ressources depuis Ermeo. Les réponses aux requêtes envoyées, vous permettront ainsi de récupérer les différentes informations de vos ressources stockées sur Ermeo. Avec cette méthode, les informations sont envoyées depuis Ermeo vers le client faisant la requête.

POST

La méthode POST vous permettra de créer une ou plusieurs nouvelles ressources (documents, équipements, utilisateurs) sur Ermeo. Ici, les données sont donc envoyées du client vers Ermeo.

POST (search)

La méthode POST permet aussi de faire des recherches sur vos ressources dans Ermeo. Vous allez donc créer vos recherches en utilisant des filtres et des tris spécifiques.

PUT

La méthode PUT vous permettra de modifier partiellement une ou plusieurs ressources existantes sur Ermeo. Ici, comme pour la méthode POST, les informations sont envoyées depuis le client vers Ermeo.

DELETE 

La méthode DELETE vous permettra de supprimer une ou plusieurs de vos ressources sur Ermeo.

Quelques règles basiques pour utiliser notre API

Comment écrire la requête ?

• L'URI (identifiant uniforme de ressource) doit être écrit en minuscule avec des tirets
• Le nom de la collection utilisée doit être au pluriel.

Le client_id est obligatoire pour exécuter chaque requête.

De quoi sont composées les en-têtes de réponses ?

Chaque réponse retournera :

• Le type de contenu (content-type)
• la longueur du contenu (content-length)

Comment représenter une ressource ?

• La ressource représentée doit être écrite au format XML ou JSON
• La convention typographique choisie pour représenter les ressources de façon uniforme est : snake_case.

Les valeurs clés doivent avoir les formats suivants selon les types :

• Chaines de caractères : entourées de guillemets
• Nombre : pas de guillemets
• Date : entourées de guillemets et écrite au format standard ISO 8601.

Exemple : 

{
 "id": 1024,
 "name": "My document",
 "start_date": "1970-01-01T12:00:27.87+00:20",
 "size" : 2.5
}