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. According to an analysis by Postman, 83 percent of all APIs use the REST paradigm (Postman, 2024). 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.

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.

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, 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, 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.