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:

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

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

Code retour HTTP et corps de réponse

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")))