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