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

curl -X GET "https://api.cegedim.cloud/itcare/health"

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-definition}/{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 (base64-encodé) 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 $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

En général, on peut utiliser la commande base64 pour encoder une chaîne de caractères. L'utilisation d'outils en ligne de commande sous Linux, par exemple :

$echo -n 'CLIENT_ID:CLIENT_SECRET' | base64
(donne la base64 du couple CLIENT_ID:CLIENT_SECRET)

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 $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&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	POST /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	PATCH /resources/1234	Met à jour partiellement un objet grâce au contenu du corps de la requête
Supprimer une ressource	DELETE	DELETE /resources	Supprime l'objet ressource identifié par l'ID 1234

Pour plus d'informations concernant l'implémentation standard RESTful:

HTTP Methods - REST API TutorialREST API Tutorial

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)

Exécutez les commandes suivantes pour installer le SDK Python d'ITCare.

pip install --ignore-installed --upgrade --trusted-host itartifacts.cegedim.cloud --index-url https://itartifacts.cegedim.cloud/artifactory/api/pypi/pypi/simple itcare
pip install --ignore-installed --upgrade --trusted-host itartifacts.cegedim.cloud --index-url https://itartifacts.cegedim.cloud/artifactory/api/pypi/pypi/simple pyoidcclient

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://api.cegedim.cloud/itcare/compute", oidc_provider="https://accounts.cegedim.cloud/auth/realms/cloud", oidc_client_id=ITCARE_USERNAME, oidc_client_secret=ITCARE_PASSWORD)

# get instances
instances = itcare.get('/instances')
  
for instance in instances:
  print("Instance {}".format(instance.get("name")))