Der Zugriff auf die Famly API wird vom Support-Team freigeschaltet. Wenn du die API für deine Einrichtung aktivieren möchtest, wende dich bitte an support@famly.de.
In diesem Artikel erfährst du, welche APIs in Famly verfügbar sind, wie du einen Access Token (Zugriffsschlüssel) erstellst und was du beim Aufbau von Integrationen beachten solltest.
Verfügbare APIs
Famly bietet sowohl eine Public API als auch eine Internal API an.
Public API
Dokumentation: https://docs.famly.co/
GraphQL Endpoint: https://famlyapi.famly.co/v1/graphql
Internal API
GraphQL Endpoints:
REST Endpoints:
Erstellung eines Access Tokens
Hier findest du die Anleitung, wie du einen Access Token erstellst, der entweder für einen einzelnen Standort oder für deine gesamte Organisation genutzt werden kann.
Wichtige Hinweise zu API-Token:
Prüfe regelmäßig das Ablaufdatum des Tokens
Du erhältst sieben Tage vor Ablauf eines Tokens eine Erinnerung
Vergebe nur die absolut notwendigen Mindestberechtigungen (Prinzip der Datensparsamkeit)
Access Token funktionieren sowohl für die Public API als auch für die Internal API
💡 Sicherheitshinweis: Teile Access Token niemals über unsichere Kanäle wie E-Mail oder Chat.
Organisations-Token erstellen
Navigiere zur Startseite
Wähle die Organisation im Drop-Down-Menü aus
Klicke auf Einstellungen
Klicke unter API-Token verwalten auf Anzeigen
Füge einen neuen Token hinzu
Standort-Token erstellen
Navigiere zu den Einstellungen
Klicke auf Integrationen
Klicke auf API-Token verwalten
Füge einen neuen Token hinzu
Public vs. Internal API
Die Public API ist die bevorzugte Option für den Aufbau von Integrationen. Falls du dort benötigte Daten nicht findest, kannst du alternativ die Internal API nutzen.
Die Internal API ist dieselbe Schnittstelle, die die Famly-App nutzt, um mit dem Backend zu kommunizieren. Sie besteht aus:
Einer GraphQL API (ähnlich der Public API, aber mit deutlich mehr Feldern)
Einer REST API
Da das Frontend darauf basiert, ist technisch gesehen alles, was in der App sichtbar ist, über diese API zugänglich.
Datenflüsse identifizieren
Der beste Weg, die Datenstruktur zu verstehen, ist die Nutzung des Netzwerk-Inspektors in deinem Browser. Führe die Aktion, die du replizieren möchtest, in der Famly-Benutzeroberfläche aus und beobachte, welche Netzwerkanfragen gesendet werden.
So siehst du sowohl die Parameter als auch die Antworten des Backends.
Empfohlene Tools
Wir empfehlen dringend die Nutzung von Postman zum Erstellen und Testen deiner API-Aufrufe. Es bietet viele hilfreiche Tools, die dir die Arbeit mit REST- und GraphQL-Workflows erleichtern.
Zugriff
Es gibt keine gesonderten Zugriffsbeschränkungen für die APIs. Die von dir erstellten API-Keys funktionieren direkt sowohl für die Public als auch für die Internal API. Der Zugriff wird von Famly auf technischer Ebene nicht formell separat vergeben oder eingeschränkt.
Einschränkungen und wichtige Bedingungen
Bevor du eine Integration mit der Internal API startest, musst du folgende Punkte ausdrücklich zur Kenntnis nehmen:
Kein Support vorhanden
Famly bietet keinen Support für Integrationen, die auf der Internal API basieren.
Falls eine Integration nicht mehr funktioniert, liegt die Fehlersuche und Reparatur in deiner Verantwortung
Keine Garantie auf Abwärtskompatibilität
Im Gegensatz zur Public API, bei der die Abwärtskompatibilität garantiert ist, kann die Internal API jederzeit und ohne Vorwarnung geändert werden (Breaking Changes), wenn Teile der App überarbeitet werden.
Keine Dokumentation
Es gibt keine offiziell aufbereitete Dokumentation für die Internal API. Endpoints müssen eigenständig über die Analyse des Netzwerkverkehrs identifiziert werden.
☝️ Der Aufbau von Integrationen erfolgt vollständig auf eigenes Risiko.