API Architecture in B2B: REST, GraphQL and Message Queues

Representational State Transfer (REST) is the dominant API paradigm in e-commerce. Shopware is built on a REST API, as are the majority of ERP systems, PIM solutions, and payment providers. REST APIs work resource-based: each entity -- product, customer, order -- is accessible via a unique URL and manipulated through the HTTP verbs GET, POST, PUT, PATCH, and DELETE.

REST's strength lies in its simplicity and ubiquity. In our experience, REST dominates the API landscape in the vast majority of B2B integrations (project experience). Developers understand REST intuitively, debugging is possible with standard tools, and the protocol's statelessness simplifies horizontal scaling. For B2B integrations, REST APIs are the natural choice when it comes to CRUD operations on business objects: creating and updating products, submitting orders, synchronizing customer data.

REST's limitations become apparent in complex query scenarios. When a frontend client needs a product's data together with availability, customer-specific price, related cross-selling products, and product reviews in a single call, REST leads to either over-fetching (too much data per endpoint) or under-fetching (multiple sequential calls needed). This problem is what GraphQL addresses.

GraphQL is a query paradigm developed by Facebook and released as open source in 2015. Unlike REST, it is not the server that defines what data an endpoint returns, but the client formulates its query and receives exactly the requested fields. For B2B frontends with their complex data requirements, GraphQL offers considerable advantages.

A typical scenario: the product detail page of a B2B store must load master data, technical attributes, customer-specific price, availability per warehouse, associated documents, and cross-selling products. With REST, this would require three to five separate API calls. With GraphQL, the client formulates a single query requesting exactly this data -- no more and no less. This reduces the number of network roundtrips and the amount of transferred data.

Shopware offers, alongside its REST API, a Store API based on similar principles. For headless implementations where a separate frontend consumes store data, GraphQL can serve as an abstraction layer between the frontend and the Shopware backend. Implementation uses a GraphQL server that aggregates the Shopware Store API and provides an optimized schema to the frontend.

Open Data Protocol (OData) is a REST-based protocol initiated by Microsoft and adopted by SAP as the standard for its APIs. OData extends REST with standardized query options such as filtering ($filter), sorting ($orderby), pagination ($top, $skip), and selective field selection ($select). For integration with SAP systems -- SAP Business One, S/4HANA, SAP Commerce -- OData is the primary interface protocol.

OData's distinguishing feature is its metadata layer: every OData service provides a $metadata document that describes all available entities, their fields, data types, and relationships. This document enables automatic generation of client code and query validation at development time. For Shopware-SAP integrations, this means a developer can programmatically query the available SAP data structures and build the mapping between SAP fields and Shopware entities on a solid data foundation.

In practice, however, SAP OData integration is not without pitfalls. SAP's OData endpoints often return more data than needed, pagination is not always reliable, and performance with large datasets can be problematic. Proven strategies include targeted use of $select and $expand for data volume reduction, delta queries for incremental synchronization, and caching in an integration layer that reduces SAP load.

Beyond the classic request-response patterns of REST and GraphQL, event-based architectural patterns are becoming increasingly important in B2B environments. In an Event-Driven Architecture (EDA), systems react to state changes instead of periodically polling for updates. When a customer places an order in the store, this event triggers a chain of reactions: the ERP receives the order, the warehouse is notified, accounting creates the invoice -- all asynchronously and decoupled.

Webhooks are the simplest form of event-based integration. The sending system configures a URL to which it sends an HTTP POST request when specific events occur. Shopware natively supports webhooks for numerous business events such as order placement, status changes, or customer registration. The advantage over polling: the receiving system does not need to regularly check whether something has changed, but is actively notified. In practice, this reduces API load significantly -- according to an analysis by Nordic APIs, by up to 95 percent compared to minute-based polling (Nordic APIs, 2024).

For more complex scenarios, a message broker or event-streaming platform is employed. These enable fan-out patterns where a single event is distributed to multiple recipients simultaneously, event sourcing where the entire state history of a business object is stored as an event chain, and saga patterns where distributed transactions are coordinated across multiple systems. For B2B portals with complex workflows -- such as multi-level approval processes for large orders -- these patterns provide the necessary flexibility and traceability.

Not every integration needs to be synchronous. When the store passes an order to the ERP, the customer does not need to wait until the ERP has processed it. When product data is updated from the PIM, it does not need to be visible in the store that same second. For these scenarios, message queues are the right architectural choice.

A message queue decouples sender and receiver both temporally and operationally. The sender places a message in the queue and immediately continues working. The receiver processes the message when ready. If the receiver is temporarily unreachable -- for instance because the ERP is being maintained -- the messages remain in the queue and are processed once the system becomes available again. This decoupling is the key to robust integrations.

In the Shopware ecosystem, Redis and RabbitMQ are the primary message brokers. Redis suits simpler scenarios and is already present as a Shopware default. RabbitMQ offers extended routing capabilities, persistent queues, and a management interface for monitoring. For extensive B2B integrations with multiple connected systems, RabbitMQ is the more stable choice.

An API gateway acts as the central entry point for all API calls. Instead of clients communicating directly with various backend systems, they address the gateway, which authenticates, authorizes, routes requests to the correct backend service, and returns the response. For B2B e-commerce landscapes with multiple APIs, a gateway offers significant advantages.

The core functions of an API gateway include authentication and authorization (OAuth 2.0, API keys, JWT tokens), rate limiting for overload protection, request routing to different backend services, response caching for frequently queried data, protocol transformation (such as SOAP-to-REST for legacy systems), and centralized logging for all API calls.

For B2B scenarios, multi-tenant authentication is particularly relevant. When different B2B customers access the store through different API keys -- for automated ordering systems or EDI connections -- the gateway must ensure that each client can only access its own data. Fine-grained resource-level permissions and IP whitelisting complement token-based authentication.

In an integration landscape with five or more connected systems, the question is not whether but when a system fails or responds erroneously. Robust error handling is therefore not optional but a central architectural concern. The most important resilience patterns for B2B integrations are retry with exponential backoff, circuit breaker, dead letter queues, and idempotency.

Retry with exponential backoff repeats failed API calls with increasing wait times between attempts. A first retry after one second, the second after two seconds, the third after four -- this pattern prevents a temporarily overloaded system from being further burdened by immediate retries. The maximum number of retries and the upper limit of wait time must be configurable.

The circuit breaker protects against cascade failures: when a backend system is persistently unreachable, the circuit breaker interrupts further calls for a defined period rather than blocking the calling system with timeouts. After the lockout period expires, a single test call is made. If the backend is reachable again, the circuit breaker resets. Otherwise, it remains active.

Idempotency is particularly critical for order submission. When an order is sent to the ERP but the call fails with a timeout, it is unclear whether the order arrived. A retry must not create a duplicate order. Through a unique idempotency key -- typically the order ID -- the receiving system ensures that an already-processed order is not created again upon re-receipt.

APIs evolve, and changes to an interface must not break existing integrations. A thoughtful versioning strategy is therefore essential. The most common approaches are URL-based versioning (/api/v1/, /api/v2/), header-based versioning (Accept header with version specification), and the use of deprecation headers that inform clients about outdated endpoints.

For B2B integrations, strict backwards compatibility is recommended: new fields can be added to responses, but existing fields must not be removed or renamed. When a fundamental change to the data structure is necessary, a new API version is introduced while the old version remains available for a defined period. For Shopware integrations, this means: with major updates to the store API, all connected systems must be checked for compatibility and adjusted if necessary.

Beyond pure versioning, a B2B integration landscape requires systematic API lifecycle management. Every API passes through the phases of design, development, publication, operation, deprecation, and decommissioning. Early communication is critical: partners and connected systems need at least six months' lead time before an API version is decommissioned. In practice, a three-phase model has proven effective: the current version receives full support, the previous version is still maintained for bug fixes, and older versions are in a sunset phase with a clear decommissioning date.

For technical implementation, an API catalog is recommended that documents all available interfaces, their versions, SLAs, and current lifecycle status. Combined with automatic deprecation warnings in API responses -- such as via the HTTP Sunset header -- consumers are notified in time about upcoming changes. According to a SmartBear study, companies with formal API lifecycle management reduce their integration-related downtime by 60 percent (SmartBear, 2024).

The more systems communicate with each other, the more important the question becomes: which system is the authoritative data source for which entity? Data governance defines these responsibilities bindingly. In a typical B2B landscape, the ERP is the leading source for prices and customer master data, the PIM system for product descriptions and media, the store for shopping carts and orders, and the CRM for contact histories and sales data.

Without clear data ownership, conflicts arise: if both the ERP and the store can modify customer addresses, which version is correct? The solution lies in a clearly defined master data management concept. For each data field, it is determined which system has authority and in which direction synchronization occurs. Bidirectional synchronization is only employed where it is functionally necessary -- such as for order status updates that are displayed in both the store and the ERP. In integration consulting, defining these data flows is one of the first and most important steps.

Integration tests are more complex than unit tests but indispensable for the stability of the overall solution. Contract testing has proven particularly effective: rather than testing the entire integration end-to-end, the API contract between two systems is tested. The consumer team defines its expectations of the API (consumer contract), and the provider team validates that its implementation meets these expectations (provider verification). Changes to the API contract are thus detected early, before they cause problems in production.

During the development phase, mock servers are indispensable. They simulate the behavior of an external system based on the OpenAPI specification and allow developers to test their integration without burdening the real system. Particularly for SAP integrations, where test environments are expensive and limited in availability, mock servers significantly reduce development time. Additionally, a set of chaos engineering tests is recommended that deliberately simulate failure conditions: What happens when the SAP interface does not respond for 30 seconds? How does the system behave with an unexpected data format? These tests ensure that resilience patterns -- circuit breaker, retry, dead letter queue -- actually function as expected.

Monitoring API integrations requires more than simple uptime checks. Latency, error rates, throughput, and the correlation of issues across system boundaries must be visible in real-time. Distributed tracing with correlation IDs makes it possible to track the path of an order through all involved systems -- from the store through the API gateway to the ERP and back -- without gaps.

Comprehensive API monitoring encompasses latency tracking per endpoint with percentile analysis (P50, P95, P99), error rate per endpoint and error type (4xx vs. 5xx), throughput in requests per second, queue depths and processing speed for asynchronous integrations, and alerting on deviations from defined thresholds. Dashboards visualizing these metrics give the operations team immediate insight into the health of the entire integration landscape.

The API architecture is the foundation upon which all digital B2B processes are built. REST for standard integrations, GraphQL for flexible frontend queries, Event-Driven Architecture for reactive workflows, and message queues for asynchronous processing together form a powerful integration toolkit. The key to stable, maintainable integrations lies in the consistent application of resilience patterns, clear API versioning, systematic data governance, and comprehensive monitoring.

Investing in a well-designed interface architecture pays off long-term: new systems can be connected faster, errors are detected and resolved early, and the overall system remains stable and performant even as complexity grows. For B2B retailers who want to future-proof their digital infrastructure, a professional API strategy is not optional but essential. Schedule an integration workshop to have your interface landscape analyzed.