Viele Unternehmen stehen heute vor einer ähnlichen Ausgangslage: Eine gewachsene Fachanwendung (oft Delphi/VCL) bildet zentrale Prozesse ab, soll aber plötzlich neue Kanäle bedienen. Ein Kundenportal benötigt Daten und Vorgänge, mobile Nutzer erwarten sichere Zugriffe, Dritt-Systeme (ERP, DMS, CRM, BI) fordern Integrationen. In dieser Situation wirkt eine REST-API wie der naheliegende Schritt. In der Praxis scheitern API-Initiativen jedoch selten an HTTP oder JSON – sondern an unklarer Verantwortungsverteilung zwischen Client, Server und Datenhaltung.
Eine tragfähige REST-Server-Architektur mit Delphi entsteht nicht, indem man „ein paar Endpunkte“ über bestehende Datenbanktabellen legt. Sie entsteht, wenn das Unternehmen fachliche Regeln, Sicherheitsanforderungen, Datenhoheit, Transaktionsgrenzen und Betriebskonzepte gemeinsam betrachtet. Der REST-Server wird damit zum stabilen Vertragslayer zwischen Fachlogik und Konsumenten: Desktop-Client, Portal, Services, Schnittstellenpartner. Genau hier spielt Delphi seine Stärken aus: schnelle Entwicklung, robuste Laufzeit, performanter nativer Code, gute Datenbankanbindung (z. B. über BDE-Ablosung mit nativer Anbindung) und die Möglichkeit, Fachlogik kontrolliert in Bibliotheken oder Servermodule zu kapseln.
Dieser Beitrag beschreibt, wie Unternehmen REST-Server mit Delphi so planen, dass sie fachlich konsistent bleiben, sich in bestehende Systemlandschaften einfügen und im Betrieb nicht zur Fehlerquelle werden. Im Fokus stehen Architekturprinzipien, typische Fallstricke in Modernisierungsprojekten und konkrete Bausteine für Sicherheit, Datenzugriff, Versionierung und Observability.
Warum eine REST-API im Unternehmen eine Architekturentscheidung ist
In einer klassischen Client-Server-Welt waren viele Regeln implizit im Desktop-Client verteilt: Validierungen, Statuswechsel, Berechnungen, teilweise sogar Berechtigungen. Solange nur ein Client existierte, war das unkritisch – fachlich unschön, aber beherrschbar. Sobald mehrere Konsumenten auf dieselben Geschäftsobjekte zugreifen, kippt das Modell:
- Ein Portal kann Client-Validierungen nicht „mitbenutzen“.
- Mobile Apps sollen offline-fähig sein, dürfen aber keine fachlichen Regeln duplizieren.
- Integrationen benötigen stabile, versionierte Verträge und klare Fehlersemantik.
- Compliance verlangt nachvollziehbare Zugriffe, Rollenmodelle und Auditfähigkeit.
Die API wird zum Ort, an dem Fachlogik, Rechte und Datenzugriff zusammenlaufen. Damit entscheidet ihre Architektur darüber, ob Ihr System langfristig erweiterbar bleibt – oder ob Sie nur neue technische Schulden erzeugen.
Delphi als Plattform für REST-Server: Stärken und typische Einsatzbilder
Delphi wird in Unternehmen häufig mit Desktop-Anwendungen assoziiert. Für REST-Server ist Delphi jedoch ebenfalls sehr gut geeignet, insbesondere wenn es um die Weiterverwendung bestehender Fachlogik oder um performante Services geht. Typische Einsatzbilder in B2B-Umgebungen:
- API-Schicht für Bestandssoftware: Bestehende Delphi-Fachanwendung bleibt als UI erhalten, der REST-Server kapselt Datenzugriffe und Regeln für neue Konsumenten.
- Backend für Portal-/Kundenbereich: Web-Portal nutzt REST-Endpunkte, die denselben Regelkern verwenden wie interne Prozesse.
- Integrations- und Schnittstellenserver: ERP/DMS/CRM-Anbindung, Import/Export, Event-Verarbeitung, zeitgesteuerte Jobs.
- Linux-Services oder Windows Services: Langlaufende Prozesse, Queue-Worker, Scheduler, Dokumenten-Workflows.
Entscheidend ist weniger das Framework-Label, sondern die Disziplin bei Schichtung, Nebenläufigkeit, Fehlerbehandlung und Deployment. Delphi erlaubt beides: schnell lieferbare Iterationen und zugleich saubere, modulare Architektur – wenn man bewusst plant.
Schichtenmodell: Layer-3 Architektur als Grundlage für langlebige APIs
Für Unternehmenssoftware hat sich ein klares, schlankes Schichtenmodell bewährt. Im Delphi-Umfeld wird das häufig als Layer-3 Architektur beschrieben. Die Begriffe variieren, die Verantwortung sollte jedoch eindeutig sein:
1) API-/Transport-Layer (HTTP, Serialization, Routing)
Dieser Layer kümmert sich um HTTP, Authentifizierung auf Protokollebene, Request/Response-Formate, Routing, Statuscodes, Content-Type, Kompression. Hier gehören keine fachlichen Regeln hinein. Ziel: Austauschbarkeit und Testbarkeit. Wenn Sie später von einer REST-API zu ergänzenden Protokollen (z. B. WebSocket, gRPC-ähnliche Patterns, Server-Sent Events) erweitern, muss der Fachkern stabil bleiben.
2) Domain-/Service-Layer (Fachlogik, Use Cases, Rechte, Transaktionen)
Hier lebt die fachliche Wahrheit: Statusmaschinen, Berechnungen, Plausibilitäten, Mandantenregeln, Rechteprüfungen auf fachlichen Aktionen. Dieser Layer sollte unabhängig vom UI sein und möglichst ohne Kenntnis von HTTP arbeiten. Idealerweise implementieren Sie Use Cases wie „Auftrag freigeben“, „Ticket schließen“, „Rechnung erzeugen“ statt nur CRUD auf Tabellen.
3) Data-Access-Layer (Repositories, SQL, FireDAC, Mapping)
Dieser Layer kapselt die Persistenz: SQL, Stored Procedures, Transaktionssteuerung, Sperrkonzepte, Connection-Pooling, DB-spezifische Besonderheiten. In Delphi ist BDE-Ablosung mit nativer Anbindung häufig die pragmatische Wahl, insbesondere bei Migrationen (BDE-Ablösung) und bei heterogenen Datenbanken (SQL Server, PostgreSQL, MariaDB, Firebird). Wichtig ist, dass der Data-Access-Layer kein HTTP-Wissen hat und keine Business-Entscheidungen trifft.
Dieses Modell reduziert die Kopplung: Änderungen am Datenmodell erzwingen keine API-Neuschreibung, und neue Clients erben automatisch dieselbe Logik. Besonders in der Delphi Modernisierung ist das die Grundlage, um gewachsene Desktop-Anwendungen schrittweise zu entkoppeln, ohne den Betrieb zu unterbrechen.
API-Design für Fachsoftware: Nicht CRUD, sondern fachliche Verträge
Viele APIs starten mit Endpunkten wie /customers, /orders, /documents und implementieren CRUD. Das ist für interne Tools manchmal ausreichend, in Fachsoftware jedoch schnell zu flach. Fachprozesse bestehen aus Zustandswechseln, Regeln, Nebenwirkungen und Berechtigungen.
Ressourcen, Aktionen und Zustände sauber modellieren
Ein besseres Muster ist die Kombination aus Ressourcen und klaren Aktionen, z. B.:
- Ressource lesen: GET /orders/{id}
- Aktion auslösen: POST /orders/{id}/release
- Dokument erzeugen: POST /orders/{id}/documents/invoice
- Status prüfen: GET /orders/{id}/status
Damit wird im API-Vertrag sichtbar, dass „Freigeben“ nicht einfach ein Feldupdate ist. Der Server kann Validierungen, Rechte, Transaktionen, Audit und Nebenprozesse zentral umsetzen.
Fehlersemantik und Validierung: für Clients planbar machen
Unternehmensclients müssen Fehler unterscheiden können: Validierungsfehler (400), fehlende Berechtigung (403), Konflikt durch parallele Änderung (409), fachliche Ablehnung (oft ebenfalls 409 oder 422), temporäre Backend-Probleme (503). Wichtig ist eine konsistente Fehlerstruktur, z. B. mit Fehlercode, Message, optionalen Feldhinweisen und einer Korrelations-ID. So kann ein Portal verständliche Hinweise anzeigen und gleichzeitig Support und Betrieb effizient nachverfolgen.
Sicherheit: Authentifizierung ist nicht gleich Autorisierung
In B2B-Kontexten scheitert Sicherheit selten an Verschlüsselung, sondern an fehlender Trennung von Identität, Rollen und fachlichen Berechtigungen. Eine REST-Server-Architektur muss daher zwei Ebenen unterscheiden:
Authentifizierung (wer ist es?)
Übliche Verfahren sind Token-basierte Ansätze (z. B. JWT oder opaque Tokens), kombiniert mit TLS und klarer Session-Strategie. Entscheidend ist: Token-Lebensdauer, Refresh-Mechanismus, Sperrung bei Rollenänderungen, sowie die Frage, ob Sie für Portale und interne Systeme unterschiedliche Identity-Provider haben. Delphi-Server können hier sowohl als Resource-Server agieren als auch – je nach Setup – Token ausstellen. In vielen Unternehmenslandschaften ist die Integration in bestehende Identity-Systeme (z. B. AD/LDAP, SSO-Lösungen) ein Kernpunkt.
Autorisierung (darf er das?)
Autorisierung gehört in den Domain-/Service-Layer. Rollen und Rechte sind selten rein technisch; sie hängen an Mandant, Standort, Organisationseinheit, Vertragsstatus oder Prozessphase. Gute Praxis:
- Rollenmodell (z. B. Admin, Sachbearbeitung, Auditor) als Basis
- Fachliche Policies („darf Rechnung nur im Status X erzeugen“, „darf nur eigene Tickets sehen“)
- Mandantenfähigkeit als Standard: jeder Request braucht Tenant-Kontext
- Auditing: wer hat welche Aktion wann ausgelöst
Die API sollte nicht nur „Zugriff erlaubt/abgelehnt“ liefern, sondern konsequent im Server verhindern, dass über Parametertricks Daten anderer Mandanten sichtbar werden. Das klingt selbstverständlich, ist in gewachsenen Systemen aber einer der häufigsten Architekturfehler, wenn man zu schnell „Tabellen auf HTTP“ legt.
Datenzugriff mit FireDAC: Transaktionen, Pooling und Datenbankstrategie
In Unternehmensanwendungen ist der Datenzugriff der Stabilitätsfaktor: Lastspitzen, Deadlocks, lange Reports, parallele Updates, Batch-Importe. FireDAC ist im Delphi-Ökosystem ein bewährter Baustein, um verschiedene Datenbanken mit einheitlichem Zugriff zu bedienen. Für eine REST-Server-Architektur sind vor allem folgende Punkte entscheidend:
Transaktionsgrenzen pro Use Case
Eine REST-API ist typischerweise request-basiert. Das passt gut zu „Transaktion pro Use Case“: Innerhalb eines Requests wird eine Transaktion geöffnet, fachliche Operationen werden durchgeführt, dann commit/rollback. Wichtig: Nicht jeden Endpunkt automatisch in eine Transaktion packen, aber bei schreibenden Aktionen konsequent sein. Leseendpunkte können je nach Isolation Level ebenfalls Transaktionen benötigen, wenn konsistente Sichten wichtig sind.
Connection-Strategie und Parallelität
Server-Parallelität bedeutet: viele gleichzeitige Requests, jede mit DB-Zugriff. Planen Sie deshalb:
- begrenzte, überwachte Poolgrößen
- Time-outs für Queries und Verbindungen
- klare Regeln für langlaufende Operationen (auslagern in Jobs/Worker)
Ein häufiger Fehler ist, teure Reports oder Massendatenexporte synchron über dieselbe API-Instanz laufen zu lassen, die auch interaktive Portalanfragen bedient. Besser ist eine Trennung: interaktiv vs. batch/async.
Datenbankmodernisierung als Teil der API-Planung
Wenn im Bestand noch ältere Datenzugriffe existieren (z. B. BDE), wird die API zum Katalysator: Sie zwingt zu klaren Datenzugriffsgrenzen. Eine kontrollierte Ablösung hin zu FireDAC reduziert Risiken und erhöht die Portabilität (PostgreSQL, MariaDB, SQL Server). Wichtig ist, das nicht als „Big Bang“ zu planen, sondern schrittweise: neue Server-Use-Cases nutzen bereits den neuen Data-Access-Layer, während Altteile nachziehen.
Versionierung und Abwärtskompatibilität: API-Verträge schützen
Unternehmen unterschätzen oft, wie teuer Breaking Changes sind. Sobald ein Kundenportal, ein Partner-System oder ein Windows-Service auf Ihrer API basiert, können Sie nicht mehr „mal schnell“ Felder umbenennen. Eine saubere Versionierungsstrategie ist daher Pflicht.
Pragmatische Regeln für Versionierung
- Keine Breaking Changes ohne Version: Felder nicht umbenennen/entfernen, Endpunkte nicht anders interpretieren.
- Erweitern statt ändern: neue Felder hinzufügen, alte als deprecated markieren.
- Kompatible Defaults: neue Pflichtfelder vermeiden oder serverseitig ableiten.
- Explizite Versionierung: z. B. /v1/… oder über Header; wichtiger als die Methode ist Konsequenz.
Für Delphi-Teams bedeutet das auch: DTOs (Data Transfer Objects) stabil halten und Mapping bewusst gestalten, statt Domain-Objekte 1:1 zu serialisieren. Das erhöht anfangs Aufwand, senkt aber langfristig Supportkosten.
Observability: Logs, Metriken und Traces von Beginn an einplanen
In einem produktiven Unternehmensbetrieb ist „funktioniert bei mir“ wertlos, wenn sich Fehler nicht reproduzieren lassen. Gerade REST-Server, die viele Konsumenten bedienen, brauchen ein Minimum an Observability:
Strukturiertes Logging mit Korrelations-ID
Jeder Request sollte eine Korrelations-ID tragen (eingehend übernehmen oder erzeugen) und in Logs wieder auftauchen. Logeinträge sollten strukturiert sein (z. B. JSON-Log), damit sie in zentrale Systeme ingestiert werden können. Mindestens relevant:
- Request-Methode, Route, Statuscode, Dauer
- User-/Tenant-Kontext (pseudonymisiert/regelkonform)
- DB-Dauer und Fehlerklasse
- Korrelations-ID für Support
Metriken für Kapazität und Fehlertrends
Für Skalierung und Stabilität benötigen Sie Metriken: Requests pro Minute, p95/p99-Latenzen, Fehlerquoten je Endpoint, DB-Pool-Auslastung, Queue-Längen. Das muss nicht „Cloud-Native Overkill“ sein, aber ohne Zahlen werden Performance-Diskussionen zur Meinungssache.
Fehler- und Ausnahmebehandlung als Architekturbaustein
Delphi-Exceptions dürfen nicht unkontrolliert nach außen „durchfallen“. Eine zentrale Exception-Middleware (oder ein globaler Handler) sollte Exceptions in konsistente Fehlerantworten übersetzen, inklusive Support-ID und sinnvoller HTTP-Codes. Intern gehören Stacktraces in sichere Logs, nicht in Clientantworten.
Synchron vs. asynchron: Langläufer aus der REST-Antwort herauslösen
Viele Unternehmensprozesse sind nicht „Request/Response in 200 ms“: PDF-Generierung, Datenimport, Schnittstellenläufe, Abgleiche, Massenänderungen, Archivierung. Diese Workloads gehören selten in einen synchronen REST-Endpoint, weil sie Threads binden, Timeouts provozieren und Nutzer blockieren.
Job-Pattern
Bewährt ist: Ein Endpoint startet einen Job, der Server liefert sofort eine Job-ID zurück. Ein weiterer Endpoint liefert Status/Ergebnis. Optional kann ein Callback/Webhook informieren. In Delphi lässt sich das mit Worker-Services, einer Job-Tabelle und klarer Statusmaschine umsetzen. Der Vorteil: Stabilität und planbare Skalierung.
Queues und Services
Je nach Umfeld kann eine Message Queue sinnvoll sein, muss es aber nicht. Wichtig ist das Prinzip: Interaktive APIs bleiben responsiv, Batch-Prozesse laufen kontrolliert, wiederholbar und beobachtbar – als Windows Services oder Linux-Services, je nach Deployment.
Deployment in Unternehmen: Windows, Linux, Container, On-Prem
Eine REST-Server-Architektur ist nur dann „fertig“, wenn sie betreibbar ist. Unternehmen unterscheiden sich stark: klassische Windows-Server, virtualisierte Linux-Hosts, Container-Plattformen, strenge Netzwerkzonen, Proxy- und Zertifikatsvorgaben. Delphi ist hier flexibel, sofern man Abhängigkeiten sauber kontrolliert.
Konfiguration und Secrets
Konfiguration muss umgebungsabhängig sein (Dev/Test/Prod). Zugangsdaten gehören nicht in EXE oder Repository. Nutzen Sie sichere Ablage (z. B. Secrets-Management der jeweiligen Plattform) und trennen Sie Konfigurationswerte von Code-Releases. Planen Sie außerdem Rotationen (DB-Passwort, API-Keys) ein, ohne das System neu bauen zu müssen.
Release- und Rollback-Strategien
Wenn mehrere Konsumenten an einer API hängen, brauchen Sie kontrollierte Releases: Migrationsskripte für DB-Änderungen, Feature-Toggles für schrittweise Aktivierung, klare Rollback-Pfade. Insbesondere Datenbankänderungen müssen rückwärtskompatibel sein, wenn ein Rollback der Serverversion möglich bleiben soll.
Integration mit Bestandssoftware: Schrittweise Modernisierung statt Big Bang
In vielen Delphi-Landschaften ist der fachliche Kern wertvoll, aber technisch „verklebt“: UI-nahe Datenzugriffe, globale Zustände, gemischte Verantwortlichkeiten. Eine REST-API kann hier sowohl Risiko als auch Chance sein. Das Ziel sollte ein Pfad sein, der mit vertretbarem Aufwand messbare Verbesserungen bringt.
Strangler-Ansatz für APIs
Statt alles umzubauen, definieren Sie fachliche Schnittpunkte, die echten Nutzen liefern: z. B. „Auftragsstatus und Dokumente für Kundenportal“, „Stammdaten-Lookup für mobile Nutzer“, „Schnittstelle für ERP-Buchungen“. Diese Use Cases werden als neue API-Funktionen implementiert, inklusive Domain-Layer und Data-Access. Der Altclient kann schrittweise auf die gleichen Server-Use-Cases umstellen, ohne dass die UI sofort neu gebaut werden muss.
Gemeinsame Fachlogik: sinnvoll, aber kontrolliert
Delphi erlaubt es, fachliche Bibliotheken sowohl im Server als auch in bestehenden Anwendungen zu nutzen. Das kann eine Brücke sein, birgt aber Gefahren: Wenn UI-Abhängigkeiten in die gemeinsame Logik sickern, verlieren Sie die Entkopplung. Eine klare Regel hilft: Gemeinsam nutzbar ist nur Logik ohne UI, ohne globale Zustände, mit klaren Interfaces und testbaren Einheiten. Alles andere bleibt getrennt.
Typische Fehler in REST-Server-Projekten – und wie man sie vermeidet
„Wir veröffentlichen einfach Tabellen“
Wenn Endpunkte direkt Tabellen spiegeln, entsteht ein instabiles System: jedes DB-Refactoring ist ein API-Breaking-Change, fachliche Regeln werden in Clients dupliziert, und Sicherheitslücken durch ungeprüfte Parameter sind wahrscheinlicher. Besser: Domain-Use-Cases und DTOs, die den Vertrag stabilisieren.
Fachliche Berechtigungen nur im Client
Clients sind austauschbar und manipulierbar. Autorisierung gehört in den Server und muss fachliche Regeln berücksichtigen, nicht nur technische Rollen.
Keine klare Strategie für Nebenläufigkeit
Parallele Updates passieren: zwei Sachbearbeiter, Portal und interner Client, oder ein Importjob. Ohne Optimistic Locking (z. B. RowVersion/Timestamp), Konfliktcodes (409) und klare Merge-Regeln entstehen Datenverluste oder „letzter schreibt gewinnt“-Fehler.
Langläufer blockieren interaktive Endpunkte
Synchrone PDF-Erzeugung oder Exporte führen zu Timeouts und „hängt“-Erlebnissen. Besser ist das Job-Pattern mit Status-Endpoints.
Observability wird nachträglich angeflanscht
Ohne Korrelations-ID, strukturierte Logs und Metriken wird jede Störung zur Suchaktion. Beobachtbarkeit ist kein Luxus, sondern Betriebsvoraussetzung.
Konkrete Checkliste für Ihre REST-Server-Architektur mit Delphi
- Schichten klar trennen: Transport (HTTP), Domain (Use Cases), Data Access (FireDAC/SQL).
- API als Vertrag verstehen: DTOs stabil halten, Versionierung planen, Breaking Changes vermeiden.
- Sicherheit zweistufig: Authentifizierung (Token) plus Autorisierung (fachliche Policies, Mandant).
- Transaktionen bewusst setzen: pro Use Case, Timeouts, Konfliktstrategie.
- Langläufer asynchron: Jobs/Worker, Windows- oder Linux-Services.
- Observability einbauen: Korrelations-ID, strukturierte Logs, Metriken, zentrale Fehlerbehandlung.
- Deployment realistisch planen: Konfiguration/Secrets, Rollback, Datenbankmigrationen.
- Modernisierung iterativ: wertvolle Use Cases zuerst, Altteile schrittweise entkoppeln.
Fazit: REST-Server entfalten ihren Wert erst als Betriebs- und Facharchitektur
Eine REST-Server-Architektur mit Delphi ist für Unternehmen dann besonders wirksam, wenn sie nicht als „technische Oberfläche“ verstanden wird, sondern als verbindender Kern zwischen Prozessen, Daten und Kanälen. Entscheidend sind saubere Schichten (Layer-3 Architektur), fachlich modellierte Endpunkte, konsequente Sicherheits- und Mandantenlogik, sowie ein Betriebsmodell mit Versionierung, Monitoring und kontrollierter Nebenläufigkeit. Damit wird die API zur stabilen Plattform: für Portale, Integrationen, Services und die schrittweise Delphi Modernisierung – ohne die fachliche Substanz eines gewachsenen Systems zu riskieren.
Wenn Sie prüfen möchten, wie sich eine belastbare REST-API auf Ihre bestehende Delphi-Landschaft aufsetzen lässt (inklusive Datenbankstrategie, FireDAC, Services und Betrieb), erreichen Sie uns hier: https://net-base-software-gmbh.de/kontakt/