API-Architektur im B2B: REST, GraphQL und Message Queues

Representational State Transfer (REST) ist das dominierende API-Paradigma im E-Commerce. Shopware basiert auf einer REST-API, ebenso die Mehrzahl der ERP-Systeme, PIM-Lösungen und Payment-Provider. REST-APIs arbeiten ressourcenbasiert: Jede Entität -- Produkt, Kunde, Bestellung -- ist über eine eindeutige URL erreichbar und wird über die HTTP-Verben GET, POST, PUT, PATCH und DELETE manipuliert.

Die Stärke von REST liegt in seiner Einfachheit und Verbreitung. Laut einer Analyse von Postman nutzen 83 Prozent aller APIs das REST-Paradigma (Postman, 2024). Entwickler verstehen REST intuitiv, Debugging ist mit Standard-Werkzeugen möglich, und die Zustandslosigkeit des Protokolls vereinfacht die horizontale Skalierung. Für B2B-Integrationen sind REST-APIs die natürliche Wahl, wenn es um CRUD-Operationen auf Geschäftsobjekten geht: Produkte anlegen und aktualisieren, Bestellungen übermitteln, Kundendaten synchronisieren.

Die Grenzen von REST zeigen sich bei komplexen Abfrageszenarien. Wenn ein Frontend-Client die Daten eines Produkts zusammen mit Verfügbarkeit, kundenspezifischem Preis, zugehörigen Cross-Selling-Artikeln und Produktbewertungen in einem einzigen Aufruf benötigt, führt REST zu entweder über-fetching (zu viele Daten pro Endpunkt) oder unter-fetching (mehrere sequenzielle Aufrufe nötig). Dieses Problem adressiert GraphQL.

GraphQL ist ein Abfrageparadigma, das von Facebook entwickelt und 2015 als Open Source veröffentlicht wurde. Im Gegensatz zu REST definiert nicht der Server, welche Daten ein Endpunkt zurückgibt, sondern der Client formuliert seine Abfrage und erhält exakt die angeforderten Felder. Für B2B-Frontends mit ihren komplexen Datenanforderungen bietet GraphQL erhebliche Vorteile.

Ein typisches Szenario: Die Produktdetailseite eines B2B-Shops muss Stammdaten, technische Attribute, kundenspezifischen Preis, Verfügbarkeit pro Lager, zugehörige Dokumente und Cross-Selling-Artikel laden. Mit REST wären dafür drei bis fünf separate API-Aufrufe nötig. Mit GraphQL formuliert der Client eine einzige Abfrage, die genau diese Daten anfordert -- nicht mehr und nicht weniger. Das reduziert die Anzahl der Netzwerk-Roundtrips und die übertragene Datenmenge.

Shopware bietet neben der REST-API auch eine Store-API, die auf ähnlichen Prinzipien basiert. Für Headless-Implementierungen, bei denen ein separates Frontend die Shop-Daten konsumiert, kann GraphQL als Abstraktionsschicht zwischen Frontend und Shopware-Backend dienen. Die Implementierung erfolgt über einen GraphQL-Server, der die Shopware-Store-API aggregiert und dem Frontend ein optimiertes Schema bereitstellt.

Open Data Protocol (OData) ist ein REST-basiertes Protokoll, das von Microsoft initiiert und von SAP als Standard für seine APIs übernommen wurde. OData erweitert REST um standardisierte Query-Optionen wie Filterung ($filter), Sortierung ($orderby), Paginierung ($top, $skip) und selektive Feldauswahl ($select). Für die Integration mit SAP-Systemen -- SAP Business One, S/4HANA, SAP Commerce -- ist OData das primäre Schnittstellenprotokoll.

Die Besonderheit von OData liegt in der Metadaten-Schicht: Jeder OData-Service stellt ein $metadata-Dokument bereit, das alle verfügbaren Entitäten, ihre Felder, Datentypen und Relationen beschreibt. Dieses Dokument ermöglicht die automatische Generierung von Client-Code und die Validierung von Abfragen zur Entwicklungszeit. Für Shopware-SAP-Integrationen bedeutet das: Ein Entwickler kann die verfügbaren SAP-Datenstrukturen maschinell abfragen und das Mapping zwischen SAP-Feldern und Shopware-Entitäten auf einer soliden Datenbasis aufbauen.

In der Praxis ist die SAP-OData-Integration jedoch nicht ohne Tücken. Die OData-Endpunkte von SAP liefern oft mehr Daten als benötigt, die Paginierung ist nicht immer zuverlässig, und die Performance bei grossen Datenmengen kann problematisch sein. Bewäährte Strategien umfassen die gezielte Nutzung von $select und $expand zur Datenmenge-Reduktion, Delta-Queries für inkrementelle Synchronisation und die Zwischenspeicherung in einem Integrations-Layer, der die SAP-Last reduziert.

Nicht jede Integration muss synchron erfolgen. Wenn der Shop eine Bestellung ans ERP übergibt, muss der Kunde nicht warten, bis das ERP die Bestellung verarbeitet hat. Wenn Produktdaten aus dem PIM aktualisiert werden, müssen diese nicht in derselben Sekunde im Shop sichtbar sein. Für diese Szenarien sind Message Queues die richtige Architekturwahl.

Eine Message Queue entkoppelt Sender und Empfänger zeitlich und operativ. Der Sender stellt eine Nachricht in die Queue und arbeitet sofort weiter. Der Empfänger verarbeitet die Nachricht, sobald er bereit ist. Wenn der Empfänger vorübergehend nicht erreichbar ist -- etwa weil das ERP gerade gewartet wird -- bleiben die Nachrichten in der Queue erhalten und werden verarbeitet, sobald das System wieder verfügbar ist. Diese Entkopplung ist der Schlüssel zu robusten Integrationen.

Im Shopware-Umfeld kommen primär Redis und RabbitMQ als Message Broker zum Einsatz. Redis eignet sich für einfachere Szenarien und ist als Shopware-Standard bereits vorhanden. RabbitMQ bietet erweiterte Routing-Möglichkeiten, persistente Queues und ein Management-Interface für die Überwachung. Für umfangreiche B2B-Integrationen mit mehreren angebundenen Systemen ist RabbitMQ die stabilere Wahl.

Ein API-Gateway fungiert als zentraler Eintrittspunkt für alle API-Aufrufe. Statt dass Clients direkt mit verschiedenen Backend-Systemen kommunizieren, adressieren sie das Gateway, das die Anfragen authentifiziert, autorisiert, an den richtigen Backend-Service weiterleitet und die Antwort zurückgibt. Für B2B-E-Commerce-Landschaften mit mehreren APIs bietet ein Gateway erhebliche Vorteile.

Die zentralen Funktionen eines API-Gateways umfassen Authentifizierung und Autorisierung (OAuth 2.0, API-Keys, JWT-Tokens), Rate Limiting zum Schutz vor Überlastung, Request-Routing an verschiedene Backend-Services, Response-Caching für häufig abgefragte Daten, Protokoll-Transformation (etwa SOAP-zu-REST für ältere Systeme) und zentralisiertes Logging für alle API-Aufrufe.

Für B2B-Szenarien ist besonders die mandantenfähige Authentifizierung relevant. Wenn verschiedene B2B-Kunden über unterschiedliche API-Keys auf den Shop zugreifen -- etwa für automatisierte Bestellsysteme oder EDI-Anbindungen -- muss das Gateway sicherstellen, dass jeder Client nur auf seine eigenen Daten zugreifen kann. Feingranulare Berechtigungen auf Ressourcenebene und IP-Whitelisting ergänzen die Token-basierte Authentifizierung.

In einer Integrationslandschaft mit fünf oder mehr verbundenen Systemen ist die Frage nicht ob, sondern wann ein System ausfällt oder fehlerhaft reagiert. Eine robuste Fehlerbehandlung ist daher nicht optional, sondern ein zentraler Architekturaspekt. Die wichtigsten Resilienz-Muster für B2B-Integrationen sind Retry mit Exponential Backoff, Circuit Breaker, Dead Letter Queues und Idempotenz.

Retry mit Exponential Backoff wiederholt fehlgeschlagene API-Aufrufe mit steigender Wartezeit zwischen den Versuchen. Ein erster Retry nach einer Sekunde, der zweite nach zwei Sekunden, der dritte nach vier Sekunden -- dieses Muster verhindert, dass ein vorübergehend überlastetes System durch sofortige Wiederholungsversuche weiter belastet wird. Die maximale Anzahl der Retries und die Obergrenze der Wartezeit müssen konfigurierbar sein.

Der Circuit Breaker schützt vor Kaskadenausfällen: Wenn ein Backend-System dauerhaft nicht erreichbar ist, unterbricht der Circuit Breaker weitere Aufrufe für einen definierten Zeitraum, statt das aufrufende System mit Timeouts zu blockieren. Nach Ablauf der Sperrzeit wird ein einzelner Test-Aufruf durchgeführt. Ist das Backend wieder erreichbar, wird der Circuit Breaker zurückgesetzt. Anderenfalls bleibt er aktiv.

Idempotenz ist besonders kritisch bei der Bestellübermittlung. Wenn eine Bestellung ans ERP gesendet wird, der Aufruf aber mit einem Timeout fehlschlägt, ist unklar, ob die Bestellung ankam. Ein Retry-Versuch darf keinesfalls eine Doppelbestellung erzeugen. Durch einen eindeutigen Idempotency-Key -- typischerweise die Bestell-ID -- stellt das Empfangssystem sicher, dass eine bereits verarbeitete Bestellung bei erneutem Empfang nicht nochmals angelegt wird.

APIs entwickeln sich weiter, und Änderungen an einer Schnittstelle dürfen bestehende Integrationen nicht brechen. Eine durchdachte Versionierungsstrategie ist daher essenziell. Die gängigsten Ansätze sind URL-basierte Versionierung (/api/v1/, /api/v2/), Header-basierte Versionierung (Accept-Header mit Versionsangabe) und die Nutzung von Deprecation-Headern, die Clients über veraltete Endpunkte informieren.

Für B2B-Integrationen empfiehlt sich eine strikte Abwärtskompatibilität: Neue Felder können zu Antworten hinzugefügt werden, bestehende Felder dürfen aber nicht entfernt oder umbenannt werden. Wenn eine grundlegende Änderung der Datenstruktur notwendig ist, wird eine neue API-Version eingeführt, während die alte Version für einen definierten Zeitraum weiter verfügbar bleibt. Für Shopware-Integrationen bedeutet das: Bei Major-Updates der Shop-API müssen alle angebundenen Systeme auf Kompatibilität geprüft und gegebenenfalls angepasst werden.

Die Überwachung von API-Integrationen erfordert mehr als einfache Uptime-Checks. Latenz, Fehlerraten, Durchsatz und die Korrelation von Problemen über Systemgrenzen hinweg müssen in Echtzeit sichtbar sein. Distributed Tracing mit Korrelations-IDs ermöglicht es, den Weg einer Bestellung durch alle beteiligten Systeme -- vom Shop über das API-Gateway zum ERP und zurück -- lückenlos nachzuvollziehen.

Ein umfassendes API-Monitoring umfasst Latenz-Tracking pro Endpunkt mit Percentil-Auswertung (P50, P95, P99), Fehlerrate pro Endpunkt und Fehlertyp (4xx vs. 5xx), Durchsatz in Requests pro Sekunde, Queue-Tiefen und Verarbeitungsgeschwindigkeit für asynchrone Integrationen, und Alerting bei Abweichungen von definierten Schwellenwerten. Dashboards, die diese Metriken visualisieren, geben dem Betriebsteam sofortigen Einblick in den Gesundheitszustand der gesamten Integrationslandschaft.

Die API-Architektur ist das Fundament, auf dem alle digitalen B2B-Prozesse aufbauen. REST für Standard-Integrationen, GraphQL für flexible Frontend-Abfragen und Message Queues für asynchrone Verarbeitung bilden zusammen ein leistungsfähiges Integrations-Toolkit. Der Schlüssel zu stabilen, wartbaren Integrationen liegt in der konsequenten Anwendung von Resilienz-Mustern, einer klaren API-Versionierung und einem umfassenden Monitoring.

Die Investition in eine durchdachte Schnittstellenarchitektur zahlt sich langfristig aus: Neue Systeme lassen sich schneller anbinden, Fehler werden früh erkannt und behoben, und das Gesamtsystem bleibt auch bei wachsender Komplexität stabil und performant. Für B2B-Händler, die ihre digitale Infrastruktur zukunftssicher aufstellen wollen, ist eine professionelle API-Strategie keine Kür, sondern Pflicht.