⚙️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/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

UsageMéthodeExempleDescription

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

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

Last updated