epilot API: Daten aus Umsystemen per REST bereitstellen

Die epilot API ist der Weg, über den Informationen aus Ihren Umsystemen in epilot ankommen. Dieser Artikel zeigt, wie Daten aus anderen CRM-Systemen, Datenbanken und Altsystemen über eine REST-API Schnittstelle bereitgestellt werden, wie sie in epilot an der richtigen Stelle landen und welche Regeln die Anbindung im Betrieb verlässlich machen.

Geschrieben hat ihn Marcel R. G. Berger. Ich bin seit über 20 Jahren Softwareentwickler und Softwarearchitekt und arbeite mit epilot als externer Consultant und Entwickler für Apps und Individualisierungen. Der Text richtet sich an IT-Verantwortliche bei Netzbetreibern, Stadtwerken und Energieversorgern, deren Daten nicht nur in epilot liegen.

Wie kommen Daten aus Umsystemen über die epilot API in epilot?

Daten aus Umsystemen kommen über einen kleinen eigenen Dienst nach epilot, der zwischen beiden Seiten vermittelt. Er liest die Quelle, übersetzt die Daten in das Datenmodell von epilot und schreibt sie über die öffentlichen APIs der Plattform.

epilot selbst bietet dafür mehrere Wege an. Die Übersicht zu Integrationen in der epilot Dokumentation nennt das Integration Toolkit für ERP-Systeme, die Batch API für viele Aufrufe in einer Anfrage, 3rd Party Journeys für externe Formulare, Webhooks für Ereignisse in Echtzeit und die öffentlichen APIs für eigene Integrationen mit voller Kontrolle.

Für Daten aus einem weiteren CRM oder einer eigenen Datenbank ist meist die Entity API von epilot der Kern. Laut Dokumentation ist sie die zentrale Datenschicht für die Geschäftsobjekte in epilot und umfasst Schema, CRUD, Suche, Relationen und ein Aktivitätsprotokoll.

Ein typischer Dienst übernimmt damit vier Aufgaben:

• Daten aus der Quelle lesen, etwa über deren REST-API oder über eine eigene Schnittstelle vor der Datenbank
• Felder zuordnen, Formate umwandeln und Pflichtangaben prüfen
• die passende Entität in epilot finden, anlegen oder aktualisieren
• Fehler erkennen, wiederholen und nachvollziehbar protokollieren

Wie so ein Dienst als Mapper mit Quarkus aufgebaut ist, beschreibt der Artikel Mapper zwischen epilot und Umsystemen mit Quarkus im Detail. Hier geht es um die Datenseite: woher die Informationen kommen und wie sie zuverlässig in epilot verfügbar werden.

Pull oder Push: Welches Muster passt zu Ihren Daten?

Welches Muster passt, hängt davon ab, wo eine Änderung zuerst bekannt wird und wie aktuell die Information in epilot sein muss. In den meisten Projekten kommen beide Muster vor, je nach Datenart.

Push heißt: Das Umsystem meldet eine Änderung, und der Dienst schreibt sie sofort nach epilot. Pull heißt: Der Dienst holt Daten ab, entweder nach Zeitplan oder genau dann, wenn epilot sie braucht.

Muster	Auslöser	Passt gut für	Worauf zu achten ist
Push aus dem Umsystem	Änderung im CRM oder Fachsystem	Daten, die in epilot schnell aktuell sein müssen	das Umsystem muss Änderungen melden können
Pull nach Zeitplan	fester Takt im Dienst	Stammdaten, die sich selten ändern	Daten sind zwischen zwei Läufen nicht ganz frisch
Pull bei Bedarf	Ereignis in epilot per Webhook	Informationen, die nur für einen Vorgang gebraucht werden	die Quelle muss in diesem Moment erreichbar sein
Abholung aus epilot	das Umsystem fragt eine Warteschlange ab	Systeme, die keine eingehenden Aufrufe annehmen	Abfragetakt und Verarbeitung im Umsystem

Für den Pull bei Bedarf ist der Ablauf meist gleich. In epilot tritt ein Ereignis ein, epilot sendet einen Webhook an den Dienst, der Dienst ruft die Daten im Umsystem ab und schreibt das Ergebnis zurück nach epilot.

Für die umgekehrte Richtung beschreibt das Integration Toolkit von epilot mit Pollable Outbound einen Weg, bei dem ein ERP eine Warteschlange abfragt, statt Webhooks zu empfangen. Das hilft bei Systemen, die hinter einer Firewall keine Aufrufe von außen annehmen.

Laut der Seite zu Rate Limits empfiehlt epilot, Ereignisse über Webhooks zu abonnieren, statt Endpunkte ständig abzufragen. Für die Richtung von epilot zu Ihrem Dienst ist Push über Webhooks also der Normalfall.

Warum lohnt sich eine eigene REST-API Schnittstelle vor Datenbank oder Altsystem?

Eine eigene REST-API Schnittstelle lohnt sich, weil sie epilot und alle anderen Abnehmer von den internen Strukturen der Datenbank entkoppelt. Sie gibt nur die Felder heraus, die gebraucht werden, und bleibt stabil, auch wenn sich Tabellen ändern.

Viele Altsysteme haben keine brauchbare API. Manche bieten nur einen direkten Datenbankzugriff, andere eine Schnittstelle, deren Antworten für epilot viel zu groß oder zu technisch sind. Ein kleiner Dienst davor löst das.

So eine Dienstschicht erfüllt mehrere Zwecke:

• Sie liefert fachliche Objekte statt Tabellenzeilen, etwa eine Kundenübersicht statt fünf verknüpfter Tabellen.
• Sie gibt nur freigegebene Felder heraus und hält alles andere zurück.
• Sie sichert den Zugriff ab, unabhängig davon, wie die Datenbank selbst geschützt ist.
• Sie lässt sich versionieren, testen und mit OpenAPI dokumentieren.

In Quarkus ist so ein Endpunkt eine einfache Klasse. Der Quarkus-Leitfaden zu REST-Diensten zeigt die Grundlagen, die Annotationen für die Dokumentation kommen aus MicroProfile OpenAPI.

@Path("/v1/customers")
@Tag(name = "Customers")
@Produces(MediaType.APPLICATION_JSON)
public class CustomerResource {

    @Inject
    CustomerRepository repository;

    @GET
    @Path("/{customerNumber}")
    @Operation(summary = "Returns the fields required for one customer")
    public Response byNumber(@PathParam("customerNumber") String customerNumber) {
        return repository.findSummary(customerNumber)
                .map(summary -> Response.ok(summary).build())
                .orElse(Response.status(Response.Status.NOT_FOUND).build());
    }
}

CustomerRepository und das zurückgegebene Objekt sind Klassen des jeweiligen Projekts. Wichtig ist das Prinzip: Die Antwort enthält nur, was die Gegenseite braucht, und die Version steht im Pfad.

Wo die Grenze zwischen Konfiguration in epilot und eigener Entwicklung typischerweise verläuft, erklärt der Artikel Wann reicht Low-Code bei epilot nicht mehr?.

Wie schreibt ein Dienst Informationen zurück nach epilot?

Ein Dienst schreibt Informationen über die öffentlichen APIs von epilot zurück, in den meisten Fällen über die Entity API. Damit sind die Daten aus dem Umsystem direkt am Vorgang, am Kontakt oder am Vertrag in epilot sichtbar.

Die Dokumentation der Entity API nennt unter anderem diese Operationen:

Operation	Methode und Pfad laut Dokumentation	Einsatz
createEntity	POST /v1/entity/{schema}	neue Entität anlegen
getEntity	GET /v1/entity/{schema}/{id}	eine Entität lesen
updateEntity	PUT /v1/entity/{schema}/{id}	bestehende Entität aktualisieren
listEntities	POST /v1/entity:list	gefiltert suchen, etwa nach einer Kundennummer
addRelations	POST /v1/entity/{schema}/{id}/relations	Entitäten miteinander verknüpfen

Jede Änderung über die Entity API erzeugt laut Dokumentation automatisch einen Eintrag im Aktivitätsprotokoll. So bleibt in epilot nachvollziehbar, dass eine Information aus einer Integration stammt.

Für viele Datensätze auf einmal gibt es die Batch API. Sie nimmt mehrere Aufrufe in einer Anfrage an, verarbeitet sie asynchron und liefert die Ergebnisse über eine Job-ID. Das Beispiel in der Dokumentation zeigt Upserts von Kontakten über einen eindeutigen Schlüssel.

Mit dem Quarkus REST Client wird die Gegenseite als Java-Interface beschrieben. Adresse und Token stehen nicht im Code, sondern in der Konfiguration.

@RegisterRestClient(configKey = "epilot-entity")
@ClientHeaderParam(name = "Authorization", value = "Bearer ${epilot.access-token}")
@Path("/v1/entity")
public interface EpilotEntityClient {

    @PUT
    @Path("/{schema}/{id}")
    @Consumes(MediaType.APPLICATION_JSON)
    Response updateEntity(@PathParam("schema") String schema,
                          @PathParam("id") String id,
                          Map<String, Object> attributes);
}

In der Konfiguration verweisen quarkus.rest-client.epilot-entity.url und epilot.access-token auf Umgebungsvariablen. Wie eine Operation mit Feldern umgeht, die nicht mitgeschickt werden, prüfen Sie vor dem Einsatz in der API-Referenz der Entity API.

Wie löst ein Dienst Events in anderen Systemen aus?

Ein Dienst löst Events in anderen Systemen aus, indem er auf ein Ereignis aus epilot reagiert und die Schnittstelle des Zielsystems aufruft. epilot liefert das Ereignis, der Dienst übersetzt es in den Aufruf, den das andere System erwartet.

Laut der Übersicht zu Integrationen erzeugt epilot Business Events für das, was in Ihrer Organisation passiert. Core Events sind in der Plattform enthalten, Custom Events definiert Ihre Organisation selbst auf Basis eigener Attribute. Beide werden über Webhooks, Automationen oder die Event Catalog API abgenommen.

Die Seite zu Core Events beschreibt gemeinsame Felder jedes Ereignisses, darunter eine eindeutige Kennung, den Zeitpunkt, den Namen und die Version des Ereignisses. Für einen Dienst ist vor allem die Kennung wertvoll: Damit erkennt er ein doppelt zugestelltes Ereignis und verarbeitet es nur einmal.

Typische Ziele für solche Events sind:

• ein weiteres CRM, in dem ein Kontakt oder Vorgang angelegt wird
• ein Fachsystem, das einen Auftrag oder eine Prüfung starten soll
• eine Datenbank, in der ein Status für Auswertungen festgehalten wird
• eine Nachrichtenschnittstelle, über die weitere Dienste informiert werden

So arbeite ich auch bei einem Netzbetreiber in Hessen. Viele Prozesse laufen dort außerhalb von epilot, und mehrere Drittsysteme sind über individuell entwickelte Schnittstellen angebunden. Mehr dazu steht im Abschnitt Aus der Praxis auf der Startseite.

Wie sichern OpenAPI und Versionierung den API-Vertrag ab?

OpenAPI und Versionierung sichern den Vertrag zwischen den Systemen ab, weil beide Seiten schriftlich und maschinenlesbar wissen, welche Felder, Typen und Fehlercodes gelten. Änderungen werden dadurch sichtbar, bevor sie im Betrieb auffallen.

Quarkus erzeugt die OpenAPI-Beschreibung direkt aus dem Code. Laut dem Quarkus-Leitfaden zu OpenAPI und Swagger UI stellt die Erweiterung quarkus-smallrye-openapi das Dokument unter /q/openapi bereit, die Swagger UI liegt unter /q/swagger-ui.

Für die Versionierung haben sich einfache Regeln bewährt:

1. Die Hauptversion steht im Pfad, etwa /v1/customers.
2. Neue, optionale Felder sind innerhalb einer Version erlaubt.
3. Umbenennen, Entfernen oder ein geänderter Typ führt zu einer neuen Version.
4. Alte und neue Version laufen für eine vereinbarte Übergangszeit parallel.

Diese Regeln gelten auch für die Gegenrichtung. Die epilot APIs haben ein eigenes API-Changelog, das bei jeder Weiterentwicklung der Integration einen Blick wert ist.

Wie wird eine REST-API Schnittstelle getestet?

Eine REST-API Schnittstelle wird auf mehreren Ebenen getestet: die Zuordnung mit Unit-Tests, der Dienst mit Integrationstests und der Vertrag gegen die OpenAPI-Beschreibung. Der Quarkus-Leitfaden zum Testen zeigt, wie @QuarkusTest die Anwendung startet und Endpunkte mit REST Assured aufruft.

Für jede Zuordnung gibt es Beispieldaten aus der Quelle und das erwartete Ergebnis für epilot. Antworten der Umsysteme und der epilot API werden im Test nachgebildet, damit kein Test gegen echte Kundendaten läuft. Fehlerfälle wie 404, 429 oder Zeitüberschreitungen gehören ausdrücklich dazu.

Wie gehen Authentifizierung, Secrets und Rate Limits zusammen?

Authentifizierung, Secrets und Rate Limits gehören zusammen, weil alle drei bestimmen, ob ein Dienst dauerhaft sicher und ohne Unterbrechung mit epilot spricht. Keines davon gehört in den Quellcode.

Laut der Dokumentation zu Access Tokens werden Aufrufe der epilot APIs mit einem Access Token im Header Authorization: Bearer autorisiert. Tokens werden in epilot unter Settings, Access Tokens verwaltet, werden nur einmal angezeigt und können ein Ablaufdatum bekommen, was die Dokumentation empfiehlt. Außerdem lassen sich Tokens auf Leserechte beschränken.

Daraus ergeben sich klare Regeln:

• Jede Integration bekommt ein eigenes Token mit genau den Rechten, die sie braucht.
• Ein Dienst, der nur liest, bekommt ein Token mit Leserechten.
• Token, Adressen und Passwörter der Umsysteme kommen aus Umgebungsvariablen oder einem Secret-Speicher, nie aus dem Repository. Wie Quarkus Werte aus verschiedenen Quellen liest, zeigt die Quarkus-Referenz zur Konfiguration.
• Tokens werden regelmäßig erneuert und bei Verdacht sofort widerrufen.

Bei den Rate Limits ist die Dokumentation eindeutig. Die Seite zu Rate Limits beschreibt, dass die API beim Überschreiten mit HTTP 429 antwortet und der Header Retry-After die Sekunden bis zum Zurücksetzen nennt. Die Limits gelten pro Organisation und Minute. Genannt werden 500 Anfragen pro Minute für schreibende Aufrufe der Entity API und 5.000 für Suchen, lesende GET-Anfragen sind ausgenommen. Werte wie diese können sich ändern, deshalb lohnt vor jedem Projekt der Blick auf die aktuelle Seite.

Ein Dienst sollte deshalb bei 429 die genannte Zeit abwarten und erst dann wiederholen. Bei größeren Mengen bündelt er Aufrufe über die Batch API, statt jede Änderung einzeln zu senden.

Wie frisch müssen die Daten sein, und wann hilft Caching?

Wie frisch die Daten sein müssen, entscheidet der Prozess, nicht die Technik. Für jede Datenart wird festgelegt, wie alt eine Information in epilot höchstens sein darf, und daraus ergibt sich, ob ein Cache erlaubt ist.

Datenart	Typische Anforderung	Umgang
Status eines laufenden Vorgangs	aktuell zum Zeitpunkt der Anzeige	kein Cache, Push oder Pull bei Bedarf
Kundenstammdaten	aktuell nach jeder Änderung	Push bei Änderung
Referenzdaten und Kataloge	ändern sich selten	Cache mit festem Ablauf
Auswertungen	Stand eines Stichtags reicht	Pull nach Zeitplan

Laut der Seite zu Rate Limits empfiehlt epilot selbst, GET-Antworten zu cachen, um unnötige Aufrufe zu vermeiden. Dasselbe gilt für Ihre Umsysteme, die oft weniger belastbar sind als eine Cloud-Plattform.

In Quarkus reicht dafür die Cache-Erweiterung. Der Quarkus-Leitfaden zum Caching beschreibt @CacheResult und die Ablaufzeit je Cache.

@ApplicationScoped
public class ReferenceDataLookup {

    @Inject
    @RestClient
    SourceSystemClient client;

    @CacheResult(cacheName = "reference-data")
    public ReferenceData byCode(String code) {
        return client.referenceData(code);
    }
}

Mit quarkus.cache.caffeine."reference-data".expire-after-write=10M gilt ein Eintrag zehn Minuten lang. Der Wert ist ein Platzhalter und wird je Datenart mit der Fachseite festgelegt.

Welche Daten dürfen aus Umsystemen nach epilot fließen?

Nach epilot fließen nur die Daten, die der Prozess dort wirklich braucht. Das ist der Grundsatz der Datenminimierung aus der DSGVO, und er macht Schnittstellen nebenbei kleiner, schneller und leichter zu prüfen.

Praktisch bedeutet das:

• Für jedes Feld ist dokumentiert, warum es übertragen wird.
• Die Dienstschicht vor der Datenbank gibt nur freigegebene Felder heraus.
• Logs enthalten Kennungen, aber keine vollständigen personenbezogenen Datensätze.
• Testdaten sind künstlich oder anonymisiert, nie Kopien echter Kundendaten.

epilot bietet laut Dokumentation zusätzlich anonymisierte Access Tokens, bei denen personenbezogene Daten in Antworten der Entity API durch Pseudonyme ersetzt werden. Die Dokumentation bezeichnet das selbst als bestmögliche Anonymisierung, eigene Attribute müssen dafür entsprechend eingeordnet sein. Für Auswertungen oder Dritte kann das sinnvoll sein.

Die Daten bleiben in Europa. Wo ich personenbezogene Daten im Auftrag verarbeite, schließen wir einen Auftragsverarbeitungsvertrag, und es besteht eine Berufshaftpflichtversicherung. Vertragspartner ist die DigitalFreedom Global LLC. Für Netzbetreiber ist auf Wunsch deutsches Recht möglich, sonst gilt das Recht von Wyoming. Abgerechnet wird in Euro, für Geschäftskunden in der EU nach VIES-Prüfung im Reverse-Charge-Verfahren. Die Angaben dazu stehen im Abschnitt Vertragspartner auf der Startseite.

Wie starten Sie mit einer REST-API Schnittstelle für epilot?

Sie starten mit einem kostenlosen Erstgespräch, in dem wir Ihre Umsysteme, Datenarten und Abläufe durchgehen. Danach ist klar, welche Daten in epilot gebraucht werden, welches Muster passt und ob die Werkzeuge von epilot schon reichen.

1. Erstgespräch: kostenlos und unverbindlich, 30 Minuten über Microsoft Teams.
2. Individuelles Angebot: zugeschnitten auf Ihre Systeme, Datenmengen und Anforderungen an Aktualität und Betrieb.
3. Umsetzung: Dienstschicht, Anbindung an die epilot API, Tests und Inbetriebnahme mit Ihren Systemen.

Der Code gehört Ihnen. Auf Wunsch übergebe ich ihn in Ihr eigenes Repository, alternativ übernehme ich Betreuung und Weiterentwicklung über einen Wartungsvertrag. Warum das wichtig ist, erklärt der Artikel Wem gehört der Integrationscode?.

Dabei ergänze ich das Consulting-Team von epilot, ich ersetze es nicht. epilot bleibt Ihr Ansprechpartner für die Plattform, ich setze dort an, wo klassische Entwicklung nötig wird. Welche Leistungen dazu gehören, steht im Abschnitt Was ich für epilot-Kunden mache.

Alle Leistungen biete ich auf Basis eines individuellen Angebots an. Weitere Antworten finden Sie in den häufigen Fragen auf der Startseite, einen Termin wählen Sie direkt im Buchungskalender.