Prérequis

Votre plan Digiforma doit inclure l'accès API GraphQL. Rendez vous dans la page des options avancées pour vérifier.

Présentation de l'API GraphQL

GraphQL est un langage moderne de requête API conçu pour améliorer la façon dont les applications récupèrent et manipulent leurs données depuis un serveur.

L'API GraphQL de Digiforma donne un accès très large au modèle de données en lecture et en écriture. C'est la solution idéale pour développer des interconnexions sophistiquées.

Principes clés :

Requêtes précises : GraphQL vous permet de demander exactement ce dont vous avez besoin, ni plus, ni moins, réduisant ainsi la quantité de données échangées.
Une seule requête, plusieurs ressources : Vous pouvez récupérer plusieurs ressources liées en une seule demande, réduisant le nombre de requêtes nécessaires au serveur.
Structure claire : Les données retournées correspondent précisément à la structure définie dans votre requête, facilitant ainsi l’intégration dans vos applications.

Exemple simple

query {
  trainee(id: 123) {
    id
    lastname
    email
  }
}

Cette requête renvoie exactement l’id, le nom et l’email du stagiaire avec l’identifiant 123.

Avantages de GraphQL

Requêtes précises : Récupérez uniquement les données dont vous avez besoin
Single endpoint : Une seule URL pour toutes vos requêtes
Typage fort : Schéma auto-documenté avec validation
Introspection : Découverte automatique du schéma

Webhooks et Subscriptions

Pour le moment, l'API GraphQL Digiforma ne propose pas de mécanisme pour être notifié d'événènements, comme des webhooks ou des Subscription en GraphQL.

Pour détecter des changements ou des nouveautés, il vous faudra implémenter un mécanisme de polling régulier dans votre code.

Interface GraphiQL pour découvrir et tester l'API

Vous pouvez découvrir et tester GraphQL directement dans votre compte grâce à une interface web intéractive: GraphiQL.

Vous pouvez tester vos requêtes et explorer le schéma GraphQL avant de développer votre propre connecteur et code en dehors de Digiforma.

Pour Utiliser GraphiQL, il vous faudra configurer l'authentification selon le processus décrit plus bas.

Dans GraphiQL l'en-tête d'authentification se configure ici:

Attention cette interface manipule les données de production de votre compte.

Tutoriel vidéo: Explorez le schéma GraphQL de l’API Digiforma.

Connexion à l'API

Endpoint

L'API GraphQL de Digiforma est accessible via ce endpoint:

https://app.digiforma.com/api/v1/graphql

Authentification

Génération du token

La méthode d'authentification utilise un token Bearer dans l'en-tête HTTP.

Connectez-vous à votre compte Digiforma
Rendez-vous dans la page de configuration de l'API
Cliquez sur "Générer un token"
Copiez le token généré

Utilisation du token

L'en-tête HTTP est nommé Autorization, sa valeur est Bearer VOTRE_TOKEN_API

Exemple en ligne de commande (récupération de tous les apprenants de la base de donnée de votre compte)

curl -X POST
 https://app.digiforma.com/api/v1/graphql
-H "Authorization: Bearer VOTRE_TOKEN_API"
 -H "Content-Type: application/json"
-d '{
 "query": "{ trainees { id firstname lastname } }"
 }'

Connaissance du modèle de données

Afin d'utiliser au mieux l'API, il est nécessaire de se familiariser avec le fonctionnement général de Digiforma pour pouvoir comprendre le modèle de données présenté dans le schéma GraphQL.

Documentation du schéma GraphQL

Le schéma comprenant toutes les structures de données et les fonctions accessibles est explorable

directement dans GraphiQL dans votre compte (tutoriel vidéo)
depuis cette page publique: documentation du schéma

Exemples d'utilisation

Vous pouvez tester ces exemples dans l'interface GraphiQL

Récupérer la liste des apprenants

query GetTrainees {
  trainees {
    id
    firstname
    lastname
    email
    phone
  }
}

Récupérer un apprenant spécifique avec toutes ses sessions de formation

Remplacer ID_D_UN_APPRENANT par un vrai ID d'apprenant.

query GetTrainee {
  trainee(id: ID_D_UN_APPRENANT) {
    id
    firstname
    lastname
    email
    phone
    company {
      id
      name
    }
    training_sessions {
      id
      name
      start_date
      end_date
    }
  }
}

Exemple en python

Voici un exemple complet qui récupère la liste des stagiaires du compte.

Remplacer YOUR_TOKEN dans le code.

import requests

query = """
query GetTrainees {
  trainees {
    id
    firstname
    lastname
    email
  }
}
"""

response = requests.post(
    'https://app.digiforma.com/api/v1/graphql',
    json={'query': query},
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    }
)

data = response.json()
print(data)

Bonnes pratiques

Optimisation des requêtes

Demandez uniquement les champs nécessaires
Utilisez la pagination pour les grandes listes
Évitez les requêtes trop profondes

Gestion des erreurs

Vérifiez toujours le champ `errors` dans la réponse
Implémentez une logique de retry appropriée
Loggez les erreurs pour le débogage

Sécurité

Stockez vos tokens de manière sécurisée
Régénérez régulièrement vos tokens
Ne jamais exposer vos tokens côté client

Performance

Utilisez la pagination pour éviter les timeouts
Mettez en cache les requêtes qui ne changent pas souvent
Évitez les requêtes N+1 en utilisant les relations GraphQL

GraphQL: l'API Digiforma