Leitfaden für die Erstellung von API Anbindungen
Eine API ist ein Webservice eines Drittprogrammes, mit welchem man aus diesem Daten lesen, Daten schreiben oder Aktionen ausführen kann. Dieser Leitfaden beschreibt Regeln für die Erstellung von lesenden API Anbindungen für OCT. Diese sind darauf ausgelegt kontinuierlich die Daten aus einem Drittsystem an OCT zu übertragen.
Regeln für lesende API Zugriff
Die Anbindung erfolgt als simple Spieglung der API Inhalt - zunächst unabhängig von der späteren Verwendung als universelle Staging Schicht
Das Staging von Werten sollte 1:1 den API Requests entsprechen
eine Staging Tabelle pro API Request
Tabellen werden per SQL Script vorab generiert, nicht automatisch durch Python / Powershellcode (für die Steuerung des Datentyps und damit Views, welche diese Tabellen nutzen sofort in der Datenbank eingespielt werden können)
der Tabellennamen entspricht dem API Request Namen
Feldnamen der Stagingtabelle entsprechen den Feldnamen des API Outputs
es werden nach Möglichkeit alle Spalten des API Request abgerufen und gespeichert, eine Einschränkung erfolgt nur bei Performanceproblemen
komplexe Rückgabewerte innerhalb von Tabellen (JSON Objekte, Arrays etc.) werden im Stagingprozess nicht aufgelöst, sondern als String gespeichert. Die Auflösung erfolgt erst innerhalb der nächsten Prozessstufe bei der Überführung in die Integration Schicht.
nur für die weitere Verarbeitung notwendige Ergänzungsspalten (meist Schlüssel) werden zusätzlich in die Stagingtabelle aufgenommen (i.d.R. die URL Parameter - z.B. Mandant oder Jahr)
Die Spiegelung soll partitioniert erfolgen können
um möglichst schnell feingranulare Aktualisierungen vornehmen zu können
manche APIs berechen pro abgerufenem Datensatz eine Gebühr, diese soll gering gehalten werden und nur notwendige Daten gelesen werden
z.B. pro Mandant, Jahr, Monat - um einen einzelnen Monat eines Mandanten aktualisieren zu können
Die Spiegelung sollte über eine Steuerungstabelle gesteuert werden können
in dieser lassen sich z.B. Mandanten / Jahre / Monate für die Spiegelung aktivieren
in dieser lassen unterschiedliche Spiegelungsbestände aktivieren (z.B. FiBu, KoRe, Offene Posten, Anlagevermögen)
Die Stagingtabellen und die Steuerungstabellen sollten darauf ausgelegt sein, mehrere Instanzen dieses Vorsystems zu stagen - z.B. zwei DATEV Systeme und die Systeme durch ein führende Spalte (z.B. “DATEV_SystemID”) zu unterscheiden
Technik
Die Umsetzung sollte aufgrund der weiteren Verbreitung bevorzugt in Python 3.13 erfolgen, alternativ in Powershell 7
es können bliebige übliche Python Bibliotheken zur Umsetzung genutzt werden (bspw. requests, pandas, pyodbc, sqlalchemie)
die Implementierung sollte kann in mehreren Scripten erfolgen
es sollten ein main script gestartet werden können, welchem ein Parameter Ausführungsmodus übergeben wird
Modus 1 = Steuerungstabelle aufbauen bzw. aktualisieren
Modul 2 = Daten gemäß Konfiguration der Steuerungstabelle lesen
Modus 3 = das System leeren / die Daten in allen Tabellen löschen
bei on-premises Installation von OCT wird das Script lokal ausgeführt werden, in der Cloud Version von OCT wird es in einem Container ausgeführt (die Bereitstellung des passenden Containers erfolgt durch Saxess)
das Script sollte vorlaufend die gelesenen Partionen in die Datenbank schreiben
FALSCH: das Script liest alle angeforderten Mandanten / Jahre in den Arbeitsspeicher und schreibt am Ende alles in die Datenbank
RICHTIG: das Script schreibt jeden angeforderten Mandanten / Jahr sofort nach Abruf in die Datenbank
die Vorteile dabei sind:
der Arbeitspeicher des lesenden Rechners wird nicht stark beansprucht
die datenhaltenden Objekte (DataFrames etc.) bleiben schlank und schnell
in der Datenbank ist kontinuierlich der Fortschritt der Datenübernahme zu sehen
Logging
Die Aktivität soll kontinuierlich in einem Logfile dokumentiert werden
Aktion mit Parametern und Zeitstempel
Anzahl gelesener Zeilen / Spalten
Fehler / Warnungen
Sicherheit
die API Credentials / Datenbankpasswörter dürfen nicht im Hauptsript main.py definiert sein. Sie müssen aus einer separaten Credentials Datei gelesen werden um das Projekt jederzeit ohne Zugangsdaten kopieren / einchecken zu können
Beispiel für DATEV Connect
Tabellennamen (hier noch im Schema integration, besser ein Schema staging erstellen)
Spalten der Steuerungstabelle