⚙️API ITCare
Débuter avec l'API ITCare ?
L'API REST ITCare respecte les spécifications standard OpenAPI.
La documentation en ligne est disponible à cette adresse : https://api.cegedim.cloud/
Exemple - Récupérer le statut de ITCare
Comment s'authentifier auprès de l'API ITCare ?
L'API ITCare utilise le protocole OAuth 2.0 pour l'authentification et les autorisations. Elle supporte les scénarios OAuth 2.0 habituels tels que ceux utilisés pour les serveurs web et les applications clientes.
Cela signifie que chaque requête API doit contenir un header "Authorization" embarquant un token d'accès précédemment obtenu grâce à des identifiants.
Comment obtenir un compte API ?
Pour interroger l'API ITCare, un compte API est requis afin de pouvoir obtenir le token d'accès obligatoire.
Pour obtenir ce compte API, une requête doit être soumise aux équipes Support cegedim.cloud en fournissant les informations suivantes :
L'organisation cible
Une description simple de l'usage cible de l'API
Comment obtenir un token d'accès ?
Pour obtenir un token d'accès, le client doit soumettre une requête au endpoint /token.
Le serveur d'autorisation exige l'authentification du client pour délivrer un access_token.
Voici un exemple de demande d'access_token :
Si la demande d'access_token est autorisée et valide, voici un exemple de réponse :
Lorsque le token expire, il est possible de :
Demander un nouvel access_token
Rafraîchir le token en interrogeant le endpoint /token
Quelles sont les conventions REST de l'API ITCare ?
L'API ITCare utilise le format JSON pour les messages (payload) à la fois en entrée (input) et en sortie (output).
Cela inclut aussi les corps des messages HTTP de type PUT, PATCH, POST et DELETE.
Elle respecte donc les standards d'une API REST en terme de verbe HTTP et de code retour HTTP.
Méthodes HTTP et type de contenu URI
Usage | Méthode | Exemple | Description |
---|---|---|---|
Demander une liste de ressources | GET | GET /resources | Renvoie une liste d'objets de type ressources |
Chercher parmi une liste de ressources | GET | GET /resources?attribute=xxxx | Renvoie une liste d'objets de type ressources filtrée sur l'attribut xxxx |
Demander une ressource | GET | GET /resources/1234 | Renvoie un objet de type ressources identifié par l'ID 123 |
Créer une ressource | POST | PATCH /resources/1234 | Crée un objet ressource grâce aux attributs JSON spécifiés dans le corps de la requête |
Mettre entièrement à jour une ressource | PUT | PUT /resources/1234 | Met à jour complètement l'objet ressource identifié par l'ID 1234 grâce aux attributs JSON spécifiés dans le corps de la requête |
Mettre partiellement à jour une ressource | PATCH | DELETE /resources/1234 | Met à jour partiellement un objet grâce au contenu du corps de la requête |
Supprimer une ressource | DELETE | POST /resources | Supprime l'objet ressource identifié par l'ID 1234 |
Pour plus d'informations concernant l'implémentation standard RESTful :
Code retour HTTP et corps de réponse
Code | Description | Corps de réponse |
---|---|---|
| Requête traitée avec succès | Varie selon ce qui a été demandé |
| Objet créé avec succès | Objet créé |
| Ordre de création de l'objet traité avec succès, la demande sera traitée de manière asynchrone | Vide ou objet de suivi décrivant le traitement de la requête asynchrone |
| Mauvaise requête - Erreur de syntaxe ou de cohérence de la requête. Doit être corrigée par l'émetteur. | Vide ou indication de l'erreur à corriger côté client |
| Accès non authentifié à la ressource | Vide |
| Accès non autorisé | Vide |
| Ressource inexistante | Vide |
| Conflit | Vide |
| Données incohérentes | Vide |
| Erreur fatale de l'API | Vide |
| Service temporairement indisponible | Vide |
Quel format de date / temps est utilisé par l'API ?
JSON ne supporte pas nativement le format Date/Time.
Tous les paramètres tagués en tant que Date par l'API sont donc des string au format ISO8601.
Z correspond à la timezone : +0200 par exemple.
Pour les requêtes GET, ne pas oublier d'URL-Encoder ces paramètres.
Puis-je lancer des actions à blanc via l'API ?
Certaines méthodes autorisent le test des appels API sans que cela ne déclenche réellement l'action dans ITCare.
La validation s'effectue cependant.
Pour activer le mode Dry Run, il suffit d'ajouter un header personnalisé dans vos requêtes HTTP :
Une fois que le serveur traitera votre requête, le même header personnalisé sera inclus dans la réponse.
Comment fonctionnent les actions asynchrones ?
Certaines méthodes sont asynchrones et nécessitent un délai après leur invocation.
Cela s'applique à des longues transactions telles que l'administration des ressources ou l'envoi de rapports.
Les méthodes qui fonctionnent de manière asynchrone répondront :
un code retour HTTP 202
un corps contenant un ID de suivi de l'opération asynchrone en cours
Voici un exemple de code en Python qui explique le fonctionnement asynchrone :
Les statuts des actions peuvent être :
IN_PROGRESS
SUCCESS
ERROR
Débuter rapidement avec Python ?
Pré-requis :
Python3
pip (pour installer le SDK)
Téléchargez l'archive suivante qui contient le SDK ITCare : itcare-sdk.tar.gz
Décompressez-le puis entrez dans le répertoire.
Exécutez les commandes suivantes pour installer le SDK Python d'ITCare.
Créer votre premier script
Last updated