APIs statt PHP-Monolith: Bestehende Systeme kontrolliert entkoppeln

Der Auftrag klingt zunächst harmlos: Ein Außendienstmitarbeiter soll zukünftig Angebote direkt aus dem CRM heraus erzeugen können – ohne Umweg über das interne Fachsystem. Technisch bedeutet das: Das CRM muss Preise, Lagerbestände und Kundenkonditionen abfragen. Und plötzlich steht die IT vor dem eigentlichen Problem. Der PHP-Monolith, der seit Jahren zuverlässig seinen Dienst tut, kennt keine externe Schnittstelle. Preislogik, Datenbankzugriff, Session-Handling und HTML-Ausgabe stecken im selben Codeblock. Jede Änderung an einer Stelle kann eine andere beschädigen.

Das ist keine Ausnahme. Viele mittelständische Unternehmen betreiben genau solche Systeme – oft über Jahre stabil, gut dokumentiert und von erfahrenen Mitarbeitern gepflegt. Das Problem ist nicht das System an sich, sondern die fehlende Trennlinie zwischen Fachlogik und technischem Zugriff. Genau hier setzt PHP Monolith mit APIs modernisieren an: nicht als großes Rewrite-Projekt, sondern als kontrollierte Entkopplung bestehender Verantwortlichkeiten.

Warum die fehlende Schnittstelle ein Wachstumshemmnis wird

Ein PHP-Monolith ist per Definition kein Fehler. Er ist das Ergebnis pragmatischer Entwicklungsentscheidungen unter Zeitdruck – und er funktioniert, solange die Anforderungen stabil bleiben. Schwierig wird es, sobald neue Systeme anklopfen: ein neues CRM, ein ERP-Modul, eine mobile App für den Außendienst, ein Buchungsportal oder ein Partner-API.

Jede neue Anbindung erfordert dann Eingriffe in den Kern des Monolithen. Entwickler müssen Geschäftslogik verstehen, die ursprünglich nie für den externen Zugriff gedacht war. Das Ergebnis sind häufig Ad-hoc-Lösungen: direkte Datenbankabfragen aus dem CRM, per E-Mail übermittelte Exporte oder manuelle Doppeleingaben, die niemand wirklich will, aber niemand Zeit findet zu ersetzen.

Die wirtschaftliche Folge ist konkret: Updates am Monolithen dauern länger, weil niemand alle Abhängigkeiten kennt. Neue Vertriebskanäle lassen sich nicht schnell anbinden. Einzelne Funktionen – etwa die Preisberechnung oder die Lagerverwaltung – können nicht unabhängig skaliert oder ausgetauscht werden. Und wenn ein kritisches Sicherheitsupdate ansteht, wie es im Oktober 2026 mit CVE-2026-109618 und CVE-2026-109619 für PHP-Systeme der Fall war, sind ungepatchte Monolithen besonders verwundbar, weil der Updateprozess komplex und risikoreich ist.

Die Lösung muss nicht ein vollständiges Rewriting sein. Sie beginnt damit, klare Grenzen zu ziehen.

Der Wunschzustand: Stabile Schnittstellen, unabhängige Komponenten

Stellen Sie sich vor, Ihr CRM ruft Kundenkonditionen per HTTP-Anfrage ab und bekommt eine strukturierte Antwort – unabhängig davon, ob dahinter PHP, eine neue Microservice-Architektur oder ein Fremdsystem steckt. Ihr ERP sendet Bestellungen in eine definierte Schnittstelle und erhält eine Bestätigung. Ihr Fachsystem kann aktualisiert, ersetzt oder erweitert werden, ohne dass CRM oder Webshop davon etwas merken.

Diesen Zustand erreicht man durch eine API-Fassade vor dem bestehenden System – kombiniert mit eindeutiger Datenverantwortung, belastbarer Authentifizierung, Idempotenz, Versionierung, Fehlerbehandlung und Monitoring. Diese sieben Bausteine sind keine Theorie. Sie sind die Grundlage jeder stabilen Systemintegration in der Praxis.

Die sieben Bausteine der kontrollierten Entkopplung

1. API-Fassade: Die Schnittstelle vor dem Monolithen

Eine API-Fassade ist eine neue, dünne Schicht, die zwischen den Monolithen und externe Systeme geschaltet wird. Sie übernimmt die Kommunikation nach außen und kapselt die interne Struktur des Monolithen vollständig. Externe Systeme sprechen nicht mehr mit der Datenbank oder internem PHP-Code, sondern mit definierten Endpunkten.

Technisch kann das ein separater Node.js- oder NestJS-Dienst sein, der per HTTP mit dem PHP-System kommuniziert – oder ein schlankes PHP-Router-Modul, das bestehenden Code hinter neuen Endpunkten verfügbar macht. Entscheidend ist nicht die Technologiewahl, sondern die klare Trennung: Was passiert intern, bleibt intern. Was nach außen geht, geht ausschließlich über die Fassade.

Ein hypothetisches Beispiel: Ein ERP-System benötigt aktuelle Lagerbestände. Bisher wurde dafür eine CSV-Datei täglich exportiert und manuell importiert. Mit einer API-Fassade ruft das ERP stattdessen GET /api/v1/inventory/{sku} auf und erhält eine aktuelle JSON-Antwort – ohne direkten Datenbankzugriff, ohne Zeitverzögerung, ohne manuelle Schritte.

2. Eindeutige Datenverantwortung: Wer hat welche Hoheit?

Vor jeder Schnittstellenentwicklung steht eine Frage, die häufig übersprungen wird: Welches System ist die führende Datenquelle für welchen Datensatz? Wenn Kundenstammdaten sowohl im CRM als auch im Fachsystem gepflegt werden, entsteht bei jeder Integration sofort Konfliktpotenzial.

Eindeutige Datenverantwortung bedeutet: Für jeden Datensatz gibt es genau ein System of Record. Das CRM führt Kontaktdaten, das ERP führt Lagerbestände, das Fachsystem führt Vertragskonditionen. Alle anderen Systeme lesen diese Daten über die API, schreiben aber nicht zurück – oder nur in klar definierten, protokollierten Schreibpfaden.

Diese Klärung ist kein technisches, sondern ein fachliches Projekt. Sie erfordert die Beteiligung der Abteilungen, die die Systeme täglich nutzen. Ohne diese Klärung scheitert jede Integration – unabhängig davon, wie gut die API gebaut ist.

3. Authentifizierung: Wer darf was abrufen?

Jede Schnittstelle, die nach außen geöffnet wird, braucht eine robuste Authentifizierung. Der verbreitetste Standard für REST API-Schnittstellen zwischen Systemen ist OAuth 2.0 – entweder mit Client Credentials (für Server-zu-Server-Kommunikation ohne Nutzerinteraktion) oder mit JWT-Tokens für kurzlebige, signierte Anfragen.

Für typische Mittelstandsintegrationen zwischen CRM, ERP und Fachsystem reicht häufig ein einfaches API-Key-Modell mit IP-Whitelisting als erste Sicherheitsebene. Wichtig ist dabei: API-Keys müssen rotierbar sein, dürfen nicht im Quellcode stehen (Stichwort Secrets-Management) und sollten pro System vergeben werden – nicht ein Generalschlüssel für alle Clients.

JWT-Token haben gegenüber API-Keys den Vorteil, dass sie kurzlebig sind und keine serverseitige Speicherung erfordern. Für komplexere Szenarien mit Nutzeranmeldung oder feinerer Berechtigungssteuerung ist OAuth 2.0 die robustere Wahl. Welches Modell passt, hängt davon ab, ob Endnutzer beteiligt sind oder reine Machine-to-Machine-Kommunikation stattfindet.

4. Idempotenz: Sicherheit bei Wiederholungsversuchen

Netzwerkfehler passieren. Ein System sendet eine Bestellung, erhält aber keine Bestätigung und sendet sie erneut. Ohne Idempotenz landet dieselbe Bestellung doppelt im System – ein klassischer Fehler bei schlecht konzipierten Integrationen.

Eine idempotente API garantiert: Wird dieselbe Anfrage mehrfach gesendet, erzeugt sie dieselbe Wirkung wie beim ersten Aufruf. Technisch wird das über eindeutige Request-IDs umgesetzt: Der Client sendet bei jeder Anfrage eine UUID (zum Beispiel im Header Idempotency-Key), und der Server speichert das Ergebnis dieser ID für einen definierten Zeitraum. Kommt dieselbe ID erneut, gibt der Server das gespeicherte Ergebnis zurück, ohne die Operation zu wiederholen.

Das ist besonders bei Schreiboperationen kritisch: Bestellungen anlegen, Zahlungen auslösen, Lagerbestände reduzieren. Leseoperationen (GET) sind von Natur aus idempotent – das Problem liegt bei POST und PATCH.

5. Versionierung: Stabilität für alle Konsumenten

Eine API ist ein Versprechen. Wenn das CRM auf GET /api/inventory angewiesen ist, darf eine interne Änderung am Fachsystem diese Anfrage nicht plötzlich ungültig machen. API-Versionierung stellt sicher, dass bestehende Clients weiter funktionieren, während neue Versionen parallel entwickelt werden.

Der einfachste Ansatz ist URL-basierte Versionierung: /api/v1/... und /api/v2/.... Beide Versionen laufen parallel, bis alle Konsumenten migriert sind. Danach wird die alte Version mit Vorlaufzeit abgekündigt. Alternativ kann die Version im HTTP-Header übergeben werden (Accept: application/vnd.api+v2+json), was sauberer ist, aber mehr Absprache mit den Konsumenten erfordert.

Für den Mittelstand ist URL-basierte Versionierung in der Regel ausreichend und verständlicher für alle Beteiligten – auch für externe Partner oder Fremdsysteme, die selten neue API-Clients deployen können.

6. Fehlerbehandlung: Klare Signale statt stille Fehler

Eine gut entworfene API kommuniziert Fehler präzise. Der HTTP-Statuscode ist dabei das erste Signal: 200 für Erfolg, 400 für fehlerhafte Anfragen, 401 für fehlende Authentifizierung, 404 für nicht gefundene Ressourcen, 429 für überschrittene Rate-Limits, 500 für serverseitige Fehler. Daneben enthält der Response-Body eine strukturierte Fehlermeldung mit Fehlercode, lesbarer Beschreibung und – wo möglich – einem Verweis auf das fehlerhafte Feld.

Was zu vermeiden ist: 200 OK mit einem Fehler im Body, leere Responses bei Fehlern oder generische Fehlermeldungen wie „Something went wrong". Diese erschweren das Debugging auf Seiten der konsumierenden Systeme erheblich.

Rate Limiting gehört ebenfalls zur Fehlerbehandlung: Überschreitet ein Client eine definierte Anzahl von Anfragen pro Zeiteinheit, antwortet die API mit 429 Too Many Requests und einem Retry-After-Header. Das schützt den Monolithen vor versehentlicher Überlastung durch fehlerhafte Clients.

7. Monitoring: Sichtbarkeit über alle Integrationen

Eine API, die niemand beobachtet, fällt erst auf, wenn etwas schiefläuft – und dann oft auf die ungünstigste Art. Monitoring für Schnittstellen bedeutet mindestens: Antwortzeiten je Endpunkt, Fehlerrate nach Statuscode, Aufrufe pro Client und Zeitraum sowie Alerts bei definierten Schwellenwerten.

Für PHP-basierte Systeme bieten sich Prometheus und Grafana als Kombination an – beide open-source, weit verbreitet und gut in bestehende Linux-Infrastrukturen integrierbar. Alternativ leisten SaaS-Lösungen dasselbe mit weniger Betriebsaufwand. Entscheidend ist nicht das Tool, sondern die Grundregel: Kein produktiver API-Endpunkt ohne Monitoring.

Audit Logs ergänzen das Monitoring um einen anderen Aspekt: Sie protokollieren, welches System wann welche Daten abgerufen oder verändert hat. Für Integrationen zwischen CRM, ERP und Fachsystem sind solche Logs essenziell – sowohl für die Fehlersuche als auch für Compliance-Anforderungen.

Praxisbeispiel: Wie eine ERP-Anbindung an ein PHP-Fachsystem aussehen kann

Das folgende Szenario ist hypothetisch, aber typisch für mittelständische Unternehmen mit gewachsener IT-Landschaft.

Ausgangslage: Ein Hersteller mit rund 80 Mitarbeitern betreibt ein PHP-basiertes Fachsystem für Auftragssteuerung und Kalkulation, das seit etwa zehn Jahren im Einsatz ist. Daten zur Auftragslage werden täglich manuell in das neu eingeführte ERP exportiert. Fehler bei der Übertragung führen zu falschen Produktionsplänen.

Ziel: Das ERP soll Auftragsdetails direkt abrufen und Produktionsfreigaben zurückmelden können.

Umsetzungsweg:

1. Analyse: Welche Daten braucht das ERP – in welchem Format, in welcher Häufigkeit? Welche Daten darf es lesen, welche schreiben? Wer ist System of Record für Auftragsmengen, Termine und Freigaben?
2. API-Fassade: Ein schlanker NestJS-Dienst wird vor dem PHP-System platziert. Er übernimmt Authentifizierung, Logging und Transformation. Der PHP-Code wird zunächst nicht angefasst.
3. Endpunkte definieren: GET /api/v1/orders/{id} liefert Auftragsdetails als JSON. PATCH /api/v1/orders/{id}/release nimmt die ERP-Freigabe entgegen und schreibt sie über eine interne PHP-Funktion zurück.
4. Idempotenz: Die PATCH-Operation erhält einen Idempotency-Key. Doppelte Freigaben werden erkannt und ignoriert.
5. Versionierung: /v1/ wird eingeführt. Für spätere ERP-Erweiterungen ist /v2/ vorbereitet, ohne bestehende Clients zu stören.
6. Monitoring: Antwortzeiten und Fehlerraten werden in einem Grafana-Dashboard sichtbar.

Das Ergebnis: Der tägliche manuelle Export entfällt. Fehler bei der Übertragung werden durch strukturierte Fehlerbehandlung und Protokollierung sofort sichtbar. Das PHP-System bleibt unverändert – und kann trotzdem schrittweise von innen heraus modernisiert werden.

Was diese Herangehensweise nicht löst – und wann ein anderer Weg sinnvoller ist

API-Fassaden sind kein Allheilmittel. Sie entkoppeln Zugriffe, aber sie sanieren keinen schlecht strukturierten Datenbankcode, keine fehlenden Transaktionssicherheiten und keine inhärenten Performanceprobleme im Kern. Wer hofft, durch eine Fassade einen grundlegend instabilen Monolithen zu stabilisieren, wird enttäuscht.

Außerdem: Wenn ein PHP-System so veraltet ist, dass es keine klaren Funktionsgrenzen mehr hat – weil Datenbankabfragen, Berechnungslogik und HTML-Ausgabe vermischt sind – dann ist das Ziehen einer sauberen API-Grenze aufwendiger. In solchen Fällen ist eine Bestandsaufnahme der internen Struktur vor der API-Entwicklung unverzichtbar.

Die Frage „Wann ist ein Rewrite sinnvoller als eine Fassade?" hat keine universelle Antwort. Grob gilt: Solange das System wartbar ist und die Kernlogik korrekt funktioniert, ist die Fassade der schnellere, risikoärmere Weg. Ist die interne Struktur so degeneriert, dass jede Änderung Monate dauert, lohnt sich die Investition in eine neue Grundarchitektur – aber auch dann in Schritten, nicht als Big-Bang-Rewrite.

CRM, ERP und Fachsysteme: Was bei individuellen Schnittstellen zu beachten ist

Die drei häufigsten Integrationsziele im Mittelstand haben unterschiedliche Anforderungsprofile:

Für CRM-Systeme wie HubSpot oder Salesforce existieren oft fertige Webhooks und OAuth-basierte Authentifizierung. Die eigentliche Integrationsarbeit liegt hier auf Seiten des PHP-Systems: Es muss die richtigen Daten in einem Format liefern, das das CRM erwartet.

Bei ERP-Systemen ist Transaktionssicherheit das zentrale Thema. Eine Bestellung, die im ERP ankommt, aber im Fachsystem nicht gespiegelt wird – weil ein Netzwerkfehler die Schreiboperation unterbrochen hat – ist ein ernstes Problem. Hier sind Idempotenz und ein belastbares Retry-Konzept keine Kür, sondern Pflicht.

Branchenspezifische Fachsysteme haben oft keine eigene API. Hier ist die API-Fassade das primäre Werkzeug: Sie macht das System integrierbar, ohne es anfassen zu müssen. Wo das System eine Datenbank direkt exponiert, ist ein zwischengeschalteter Dienst, der Datenbankzugriffe kapselt und nach außen als saubere REST-API erscheinen lässt, der pragmatischste Einstieg.

Was SW Business Solutions in diesem Bereich leistet

SW Business Solutions entwickelt API-Fassaden, individuelle Schnittstellen und Integrationsdienste für bestehende PHP-Systeme sowie moderne Anwendungen. Das schließt die Analyse bestehender Systemgrenzen, die Konzeption der API-Architektur, die Entwicklung und Dokumentation der Endpunkte sowie das Aufsetzen von Monitoring und Logging ein.

Unsere Erfahrung aus Projekten wie dem MobiKart-Buchungssystem – bei dem Backend, Buchungslogik und externe Dienste über eine sauber definierte NestJS-API miteinander verbunden wurden – zeigt: Der Schritt von einem gewachsenen System zu stabilen, wartbaren Schnittstellen ist planbar und kontrollierbar, wenn er systematisch angegangen wird. Auch beim HPS Pitbike Backend – NestJS REST-API haben wir eine klare API-Struktur als Grundlage für Buchungswebsite und Admin-Dashboard aufgebaut.

Die Grundlage ist immer eine ehrliche Bestandsaufnahme: Welche Daten fließen wohin? Welche Systeme sind beteiligt? Welche Grenzen sind bereits vorhanden, welche müssen erst gezogen werden?

Wenn Sie diese Fragen für Ihre Systemlandschaft klären wollen, ist ein erstes Gespräch der sinnvolle nächste Schritt – unverbindlich, aber konkret: Entkopplung und Schnittstellen der Altanwendung analysieren lassen.

Einstieg: Was vor der ersten API-Zeile geklärt sein muss

Bevor auch nur ein Endpunkt implementiert wird, sollten folgende Fragen schriftlich beantwortet sein:

• Welche Systeme sind beteiligt, und wer betreibt sie?
• Welche Daten werden ausgetauscht – in welchem Format und welcher Häufigkeit?
• Wer ist System of Record für welchen Datensatz?
• Welche Schreiboperationen sind erlaubt, welche nicht?
• Wie wird Authentifizierung organisiert, und wer verwaltet die Zugangsdaten?
• Wie werden Fehler kommuniziert, und wer behebt sie?
• Wer monitort die Schnittstelle im laufenden Betrieb?

Diese Klärung dauert typischerweise ein bis drei Workshops – je nach Systemkomplexität und Beteiligten. Sie ist keine Bürokratie, sondern die Grundlage, auf der eine stabile Integration steht. Projekte, die diesen Schritt überspringen, landen regelmäßig bei denselben Problemen wie der ursprüngliche Monolith: ungeklärte Abhängigkeiten, unklare Verantwortlichkeiten, schwer nachvollziehbare Fehler.

Wer PHP-Systeme kontrolliert modernisieren will – ob durch Fassaden, schrittweise Extraktion einzelner Domänen oder gezielte Systemintegration im Mittelstand – braucht diese Klarheit als Ausgangspunkt. Der technische Teil ist lösbar. Die fachliche Klärung ist der eigentlich kritische Weg.