Wenn ein Altsystem modernisiert werden soll, ist der erste Vorschlag oft ein neues Frontend. Das ist verständlich: Die Oberfläche ist das, was alle sehen, und sie sieht am ältesten aus.
Es ist trotzdem die falsche Reihenfolge. Ein neues Frontend auf einem System ohne Schnittstelle bedeutet, dass die neue Oberfläche an dieselben Seitenaufrufe gekoppelt wird wie die alte, nur mit mehr JavaScript dazwischen. Der Umbau kostet Monate und ändert an der Änderbarkeit des Systems nichts.
Die Reihenfolge, die trägt, ist umgekehrt: erst eine Schnittstelle, dann alles, was daran hängen kann. Dieser Artikel beschreibt, wie diese Schicht aussieht, wo sie geschnitten wird und was sie ausdrücklich nicht tun darf.
Warum die Schnittstelle vor dem Frontend kommt
Ein Monolith, der HTML ausliefert, hat genau einen Verbraucher: den Browser. Alles andere, was Daten braucht, behilft sich: ein Export als CSV, ein Skript, das direkt in die Datenbank sieht, eine Seite, die jemand maschinell ausliest.
Eine Schnittstelle ändert diese Lage grundlegend, und zwar nicht wegen der Technik, sondern wegen der Zahl der Optionen danach. Mit ihr sind drei Dinge möglich, die vorher nicht gingen: eine neue Oberfläche, ein herausgelöster Dienst, eine Anbindung durch einen Partner. Ohne sie ist jedes dieser drei Vorhaben ein eigener Umbau am Monolithen.
Der praktische Unterschied zeigt sich beim ersten herausgelösten Dienst. Wenn eine Schnittstelle existiert, ist das Herauslösen eine Umleitung: Der neue Dienst bedient dieselben Aufrufe. Ohne sie muss der Dienst nachbauen, was der Monolith in seinen Seitenaufrufen tut, und das ist ungleich mehr Arbeit.
Was diese Schicht ist, und was nicht
Die Schicht ist Code im Monolithen: ein Satz Endpunkte, der dieselbe Logik aufruft wie die bestehenden Seiten und die Ergebnisse als JSON zurückgibt. Sie ist kein zusätzliches System.
Drei Abgrenzungen sparen Geld.
Kein Gateway-Produkt am Anfang. Ein verwaltetes Gateway löst Probleme, die bei einem Verbraucher und zehn Endpunkten nicht existieren: Drosselung je Kunde, Schlüsselverwaltung, Nutzungsabrechnung. Es kommt dazu, wenn es einen Grund gibt, nicht vorher.
Keine vollständige Abbildung des Systems. Der Reflex, für jede Tabelle Endpunkte anzulegen, erzeugt hundert Endpunkte, von denen drei benutzt werden. Gebaut wird, was der erste Verbraucher braucht.
Kein Umbau der bestehenden Seiten. Die alten Seiten bleiben, wie sie sind. Die Schnittstelle liegt daneben, nicht darunter, und genau deshalb ist sie in Wochen statt Monaten fertig.
Derselbe Schnitt entscheidet später, welcher Teil zuerst herausgelöst wird: Welchen Service Sie zuerst aus dem Monolithen lösen.
Der Schnitt: nach Anwendungsfall, nicht nach Tabelle
Die wichtigste Entscheidung ist, was die Endpunkte abbilden. Zwei Wege stehen offen, und der naheliegende ist der schlechtere.
Der naheliegende bildet die Datenbank ab: /api/kunden, /api/bestellungen, /api/positionen. Das ist schnell geschrieben und verlagert die Arbeit zum Verbraucher: Für eine Bestellübersicht braucht der drei Aufrufe und muss wissen, wie sie zusammengehören. Damit steckt Fachlogik im Frontend, und beim zweiten Verbraucher ein zweites Mal.
Der bessere bildet ab, was jemand tun will:
GET /api/v1/bestellungen?status=offen&seit=2026-11-01
GET /api/v1/bestellungen/{nr} # mit Positionen und Kunde
POST /api/v1/bestellungen/{nr}/stornierung
GET /api/v1/kunden/{nr}/offene-postenDer dritte Eintrag ist der, an dem sich die beiden Wege unterscheiden. Eine Stornierung ist kein Ändern eines Feldes, sondern ein Vorgang mit Regeln: Sie ist nur in bestimmten Zuständen erlaubt, sie erzeugt eine Gutschrift, sie meldet das Lager. Als eigener Endpunkt liegen diese Regeln im Monolithen, wo sie ohnehin schon stehen. Als PATCH auf ein Statusfeld müsste der Verbraucher sie kennen.
Die Regel dazu: Jeder Endpunkt, der einen Zustand ändert, bildet einen fachlichen Vorgang ab, keinen Datensatz. Für das Lesen ist die Datensicht in Ordnung, dort ist der Schaden gering.
Versionierung, aber klein
Das /v1/ im Pfad kostet nichts und erspart eine unangenehme Diskussion in zwei Jahren. Wichtiger als der Mechanismus ist die Zusage dahinter, und sie lässt sich in drei Sätzen aufschreiben.
- Neue Felder dürfen jederzeit dazukommen. Verbraucher ignorieren, was sie nicht kennen. Das gehört in die Beschreibung der Schnittstelle, damit sich niemand darauf verlässt, dass die Antwort genau diese Felder hat.
- Felder verschwinden nicht innerhalb einer Version. Ein Feld, das nicht mehr gepflegt wird, bleibt stehen und wird als veraltet gekennzeichnet.
- Eine neue Version gibt es nur für Brüche, und die alte läuft weiter, bis die Verbraucher gewechselt haben. Wer das nicht will, baut keine neue Version.
Für die Beschreibung selbst reicht eine OpenAPI-Datei im Repository. Sie muss nicht schön sein; sie muss aktuell sein, und dafür gehört sie neben den Code und nicht in ein Wiki.
Authentifizierung: die Stelle, an der es scheitert
Hier gehen die meisten Vorhaben dieser Art in die Knie, und der Grund ist immer derselbe: Der Monolith hat eine Sitzungsanmeldung mit Cookies, und die passt nicht zu einer Schnittstelle.
Drei Wege stehen offen, und die Wahl hängt allein vom ersten Verbraucher ab.
Sitzung weiterverwenden. Wenn der erste Verbraucher eine neue Oberfläche auf derselben Domain ist, funktioniert die bestehende Anmeldung unverändert. Das ist der schnellste Weg und er trägt erstaunlich weit. Er endet, sobald ein Verbraucher von außerhalb kommt.
Statische Schlüssel je Verbraucher. Für ein anderes System im eigenen Haus oder einen Partner. Unspektakulär, ausreichend und in einer Stunde gebaut, solange die Schlüssel je Verbraucher einzeln sind und einzeln zurückgezogen werden können.
Token mit Ablauf. Für alles, was mit Benutzeridentität zu tun hat und nicht im Browser derselben Domain läuft. Der Mehraufwand ist real und lohnt sich erst dann.
Die Empfehlung ist die einfachste Variante, die für den ersten Verbraucher reicht, und der ausdrückliche Verzicht darauf, gleich die dritte zu bauen. Die Umstellung später ist kleiner, als es scheint: Sie betrifft eine Stelle in der Schicht.
Was dagegen von Anfang an dazugehört, ist die Trennung von Anmeldung und Berechtigung. Wer ein Recht hat, entscheidet der Monolith mit seiner bestehenden Logik. Die Schicht prüft nur, wer da ist, und reicht die Frage nach dem Dürfen weiter.
Was die Schicht nicht tun darf
Die Schicht ist Übersetzung, keine Fachlichkeit. Das klingt selbstverständlich und wird regelmäßig verletzt, weil es bequem ist.
Der typische Verlauf: Der Verbraucher braucht eine Summe, die es im Monolithen nicht gibt. Sie ist schnell im Endpunkt gerechnet, also wird sie dort gerechnet. Drei Monate später gibt es zwei Wahrheiten über dieselbe Zahl, weil die Seite im Monolithen anders rechnet.
// Falsch: die Schicht rechnet. Die Seite im Monolithen rechnet anders,
// und in einem halben Jahr weiss niemand mehr, welche Zahl stimmt.
$offen = 0;
foreach ($bestellungen as $b) {
if ($b['status'] !== 'bezahlt') {
$offen += $b['betrag'] - $b['gutschrift'];
}
}
// Richtig: die Fachlogik liegt da, wo sie schon liegt. Fehlt sie dort,
// wird sie dort ergaenzt und von beiden Seiten benutzt.
$offen = $this->offenePostenRechner->fuerKunde($kundeId);Die Prüfung dafür ist einfach: Wenn ein Endpunkt eine Zahl liefert, die auf keiner Seite des Monolithen steht, wird gerade Fachlogik in die Schicht verlagert. Das ist nicht immer falsch, und es ist immer eine bewusste Entscheidung wert.
Ob überhaupt ein neues Frontend nötig ist, ist eine Frage für sich: Server-gerenderte Oberflächen modernisieren, ohne SPA.
Was danach möglich ist
Der Aufwand für eine erste Schnittstelle liegt bei zwei bis vier Wochen für zehn bis fünfzehn Endpunkte, wenn die Logik im Monolithen aufrufbar ist. Was danach möglich ist, rechtfertigt ihn.
Eine neue Oberfläche wird ein eigenes Vorhaben. Sie hängt an der Schnittstelle, nicht am Monolithen, und sie kann Seite für Seite entstehen, während die alten Seiten weiterlaufen.
Ein herausgelöster Dienst wird eine Umleitung. Wenn später ein Teil in einen eigenen Dienst wandert, ändert sich für den Verbraucher nichts: Derselbe Aufruf landet an einer anderen Stelle. Ohne Schnittstelle wäre dasselbe ein Umbau bei jedem Verbraucher.
Anbindungen kosten Tage statt Wochen. Der Partner, der Bestellungen abholen will, das andere System im Haus, die Auswertung: All das sind Aufrufe statt Sonderlösungen, und es fällt keine weitere direkte Abfrage in die Datenbank an.
Der letzte Punkt ist der unterschätzte. Jeder direkte Datenbankzugriff von außen ist ein Vertrag, den niemand geschlossen hat und der jede spätere Schemaänderung teurer macht. Eine Schnittstelle ist die Stelle, an der man solche Zugriffe nach und nach einsammelt.
Wie ich Schnittstellen in bestehenden Systemen aufsetze, steht auf einer eigenen Seite. Und wenn die Frage danach lautet, welcher Teil als Erster aus dem Monolithen herausgelöst wird: wie das technisch neben einem PHP-System aussieht, steht in einem eigenen Artikel.
Dieser Artikel gehört zu einer Reihe über Systeme, die es schon gibt. Der Rückblick ordnet alle Artikel der Reihe nach Anlass.
