Français
Poser une question…
K
Links
⚙️

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://apidocs.cegedim.cloud
Exemple - Récupérer le statut de ITCare
curl -X GET "https://itcare.cegedim.cloud/itcare/api/status"

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.
curl -X GET "https://itcare.cegedim.cloud/itcare/api/endpoint" -H "Authorization: Bearer {token}"

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 :
curl -X POST "https://accounts.cegedim.cloud/auth/realms/cloud/protocol/openid-connect/token " \
-H "Authorization: Basic base64({client_id}:{client_secret})" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Request Body: grant_type=client_credentials"
Si la demande d'access_token est autorisée et valide, voici un exemple de réponse :
{
"access_token":"...",
"expires_in":1200,
"refresh_expires_in":7200,
"refresh_token":"...",
"token_type":"bearer"
}
Lorsque le token expire, il est possible de :
  • Demander un nouvel access_token
  • Rafraîchir le token en interrogeant le endpoint /token
curl -X POST "https://accounts.cegedim.cloud/auth/realms/cloud/protocol/openid-connect/token" \
-H "Authorization: Basic base64({client_id}:{client_secret})" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Request Body: grant_type=refresh_token&refresh_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
200
Requête traitée avec succès
Varie selon ce qui a été demandé
201
Objet créé avec succès
Objet créé
202
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
400
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
401
Accès non authentifié à la ressource
Vide
403
Accès non autorisé
Vide
404
Ressource inexistante
Vide
409
Conflit
Vide
422
Données incohérentes
Vide
500
Erreur fatale de l'API
Vide
503
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.
YYYY-MM-DDTHH:MM:SS.sssZ
Z correspond à la timezone : +0200 par exemple.
2016-06-01T12:27:19.000+0200
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 :
ITCare-DryRun: true
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 :
/"""
Launch action and get its descriptor
"""
action = itcare.post('/api/resource', payload=my_payload)
"""
Loop on getting its status
"""
while action['status']=='IN_PROGRESS':
time.sleep(1)
action = itcare.get('/api/actions/{}'.format(action['id']))
"""
Print its status
"""
print action['status']
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.
pip install pyoidcclient
pip install itcare

Créer votre premier script

# lib import
from itcare import ITCareService
# API Account on ITCare
ITCARE_USERNAME="my-client-id"
ITCARE_PASSWORD="my-client-password"
# Create API client
itcare = ITCareService(url="https://itcare.cegedim.cloud/itcare", oidc_provider="https://accounts.cegedim.cloud/auth/realms/cloud", oidc_client_id=ITCARE_USERNAME, oidc_client_secret=ITCARE_PASSWORD)
# get instances
instances = itcare.get('/api/instances')
for instance in instances:
print("Instance {}".format(instance.get("name")))