API Gateway

Das API Gateway ist der zentrale Eingang zu buzzle Commerce Core. Alle Zugriffe von aussen laufen über diesen Dienst: Er authentifiziert Anfragen, leitet sie an das zuständige Modul weiter und blendet die interne Struktur der Plattform nach aussen ab. Statt viele einzelne Dienste direkt anzusprechen, kennt eine Client-Anwendung nur eine Adresse – das Gateway.

Aufgabe

Das Gateway erfüllt drei Kernaufgaben:

Authentifizierung – es prüft das mitgeschickte Zugriffstoken, bevor eine Anfrage weitergeleitet wird.
Routing – es leitet jede Anfrage an das Modul weiter, das für sie zuständig ist.
Zusammenführung – es fasst die vielen Module hinter einer einzigen, einheitlichen Adresse zusammen.

Technisch basiert das Gateway auf ASP.NET Core und YARP (Yet Another Reverse Proxy), der Reverse-Proxy-Bibliothek von Microsoft.

Dynamische Modul-Discovery

Das Besondere am buzzle-Gateway: Es kennt seine Routen nicht fest, sondern ermittelt sie zur Laufzeit. Ein Hintergrunddienst fragt die Service Platform regelmässig über deren /modules-Endpunkt ab, welche Module aktuell verfügbar sind, und baut daraus die Proxy-Konfiguration auf.

Das hat mehrere Vorteile:

Module lassen sich hinzufügen oder entfernen, ohne das Gateway neu zu konfigurieren. Sobald ein neues Modul in der Plattform läuft, wird es automatisch erreichbar.
Robustheit gegen Startreihenfolge: Ist die Plattform beim Start des Gateways noch nicht bereit, versucht es die Discovery in kurzen Abständen erneut. Erst wenn alle konfigurierten Endpunkte gesund sind, schaltet es auf das normale Aktualisierungsintervall zurück.
Zwischenspeicherung des letzten guten Standes: Fällt die Discovery vorübergehend aus, arbeitet das Gateway mit der zuletzt bekannten funktionierenden Konfiguration weiter, statt Routen zu verlieren.

Jedes entdeckte Modul wird unter seinem eigenen Pfad-Präfix erreichbar – etwa /business, /order oder /search –, samt der zugehörigen Swagger- und Health-Check-Endpunkte.

Sicherheit: OAuth2-Token-Introspection

Der Zugang zur Plattform ist standardkonform abgesichert. Das Gateway nutzt OAuth2-Token-Introspection: Zu jeder Anfrage prüft es das mitgeschickte Zugriffstoken bei Zitadel und stellt sicher, dass es gültig ist, bevor die Anfrage weitergereicht wird. Anfragen ohne gültiges Token werden abgewiesen.

Die dafür nötigen Angaben – die Adresse des Identity-Servers (Authority), die Introspection-Zugangsdaten und optional ein fester Introspection-Endpunkt – werden über die Konfiguration gesetzt. So lässt sich das Gateway an unterschiedliche Umgebungen anpassen, etwa wenn der Identity-Server innerhalb eines Containers unter einer anderen Adresse erreichbar ist als von aussen.

Management-Oberfläche

Zusätzlich zum Proxy liefert das Gateway eine eingebettete Management-SPA aus – eine Weboberfläche, die unter dem Pfad /management bereitsteht. Ihre Laufzeitkonfiguration (Identity-Server, Client-ID, aktive Sprachen, Rollen-Claims, Branding) kann entweder aus einer statischen Datei oder vollständig aus Umgebungsvariablen bezogen werden. Damit lässt sich eine komplette Gateway-Instanz – Backend wie Frontend – allein über Umgebungsvariablen konfigurieren, ohne Dateien einzuhängen.

Health-Checks und Beobachtbarkeit

Das Gateway überwacht sich selbst und seine Abhängigkeiten. Unter /healthcheck liefert es einen maschinenlesbaren Gesundheitsstatus, unter /health eine grafische Übersicht. Geprüft werden unter anderem:

die Modul-Discovery (erreicht das Gateway die Plattform?),
die Routen- und Cluster-Konfiguration des Reverse Proxy,
die OIDC-Introspection (ist der Identity-Server erreichbar?),
der Status der einzelnen entdeckten Module (je Modul eine eigene Statuskarte).

So ist auf einen Blick erkennbar, ob der Eingang zur Plattform und die dahinterliegenden Dienste einsatzbereit sind.

Einordnung

Das API Gateway ist die einzige Komponente, die von aussen direkt angesprochen wird. Es hält die Plattform zusammen, ohne selbst fachliche Logik zu enthalten – diese liegt vollständig in der Service Platform und ihren Modulen.