Voraussetzungen
Ihr Digiforma-Tarif muss den Zugriff auf die GraphQL-API beinhalten. Überprüfen Sie dies auf der Seite Erweiterte Optionen in Ihrem Konto.
Einführung in die GraphQL-API
GraphQL ist eine moderne Abfragesprache für APIs, die entwickelt wurde, um den Datenzugriff zwischen Anwendungen und Servern effizienter und flexibler zu gestalten.
Die GraphQL-API von Digiforma bietet umfassenden Zugriff auf das Datenmodell – sowohl zum Lesen als auch zum Schreiben – und ist damit die ideale Lösung für die Entwicklung komplexer Integrationen.
Zentrale Vorteile:
Präzise Abfragen: Fordern Sie genau die Daten an, die Sie benötigen – nicht mehr und nicht weniger.
Eine Abfrage, mehrere Ressourcen: Kombinieren Sie zusammenhängende Daten in einer einzigen Anfrage.
Klar strukturierte Antworten: Die Rückgabestruktur entspricht exakt Ihrer Abfrage – ideal für die Integration in eigene Anwendungen.
Einfaches Beispiel
query {
trainee(id: 123) {
id
lastname
email
}
}Diese Abfrage liefert die ID, den Nachnamen und die E-Mail-Adresse des Teilnehmers mit der ID 123.
Vorteile von GraphQL
Gezielte Datenabfrage
Nur ein Endpunkt für alle Abfragen
Starke Typisierung mit automatischer Dokumentation
Schema-Introspektion zur Erkundung der verfügbaren Daten
Webhooks und Subscriptions
Derzeit unterstützt die GraphQL-API von Digiforma keine Benachrichtigungsmechanismen wie Webhooks oder GraphQL-Subscriptions.
Um Änderungen zu erkennen, müssen Sie einen regelmäßigen Polling-Mechanismus in Ihrem Code implementieren.
GraphiQL – Interaktive Oberfläche zum Testen
Sie können GraphQL direkt in Ihrem Konto über die interaktive GraphiQL-Weboberfläche testen.
Hier können Sie Abfragen ausprobieren und das Datenmodell erkunden, bevor Sie eigene Integrationen umsetzen.
Authentifizierung in GraphiQL
Um GraphiQL nutzen zu können, müssen Sie die Authentifizierung gemäß dem weiter unten beschriebenen Verfahren konfigurieren.
In GraphiQL wird der Authentifizierungs-Header an folgender Stelle eingerichtet:
Achtung: Diese Oberfläche arbeitet mit den Produktivdaten Ihres Kontos.
Verbindung zur API
Endpunkt
Die GraphQL-API von Digiforma ist über folgenden Endpunkt erreichbar:
https://app.digiforma.com/api/v1/graphql
Authentifizierung
Token-Erstellung
Die Authentifizierung erfolgt über ein Bearer-Token im HTTP-Header.
Melden Sie sich in Ihrem Digiforma-Konto an.
Gehen Sie zur Seite API-Konfiguration.
Klicken Sie auf „Token generieren“.
Kopieren Sie das generierte Token.
Verwendung des Tokens
Der HTTP-Header heißt Authorization, sein Wert lautet:
Bearer IHR_API_TOKEN
Beispiel in der Kommandozeile
(Abruf aller Teilnehmenden aus der Datenbank Ihres Kontos)
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 } }"
}'
Datenmodell verstehen
Um die API effektiv zu nutzen, sollten Sie sich mit dem allgemeinen Datenmodell von Digiforma vertraut machen. Dieses ist über das GraphQL-Schema dokumentiert.
GraphQL-Schema-Dokumentation
Das vollständige Schema (inkl. Datenstrukturen und Funktionen) ist verfügbar:
Direkt im GraphiQL-Interface Ihres Kontos
Über diese öffentliche Seite: (Link zur Schema-Dokumentation)
Beispielabfragen
Sie können diese Beispiele in der GraphiQL-Oberfläche testen.
Liste der Teilnehmenden abrufen
query GetTrainees {
trainees {
id
firstname
lastname
email
phone
}
}Einzelnen Teilnehmenden und seine Schulungssitzungen abfragen
Ersetzen Sie ID_D_UN_APPRENANT durch eine echte Teilnehmer-ID.
query GetTrainee {
trainee(id: ID_D_UN_APPRENANT) {
id
firstname
lastname
email
phone
company {
id
name
}
training_sessions {
id
name
start_date
end_date
}
}
}Python-Beispiel
Ersetzen Sie YOUR_TOKEN im Code durch Ihren tatsächlichen API-Token.
import requests
query = """
query GetTrainees {
trainees {
id
firstname
lastname
}
}
"""
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)
Best Practices
Anfrageoptimierung
Fordern Sie nur die Felder an, die Sie wirklich benötigen
Verwenden Sie Paginierung für große Datenmengen
Vermeiden Sie zu tiefe, verschachtelte Abfragen
Fehlerbehandlung
Überprüfen Sie immer den
errors-Block in der AntwortImplementieren Sie eine Retry-Logik
Loggen Sie Fehler für das Debugging
Sicherheit
Speichern Sie Ihre Tokens sicher
Erneuern Sie Tokens regelmäßig
Geben Sie Tokens niemals im Client-Code preis
Performance
Verwenden Sie Pagination, um Timeouts zu vermeiden
Cachen Sie häufig genutzte Anfragen
Vermeiden Sie N+1-Anfragen durch Nutzung von Relationen