Commerce Api Gateway

Commerce API Gateway

Overview

An API gateway sits between storefront clients and the set of backend commerce services, providing a single entry point for authentication, rate limiting, caching, and request routing. In composable commerce architectures, the gateway aggregates APIs from disparate services (catalog, cart, search, CMS) so the frontend makes one or a few calls rather than dozens. This skill covers building a GraphQL Federation gateway with Apollo Router, a REST aggregation BFF, and applying cross-cutting concerns (auth, rate limiting, observability) at the gateway layer.

When to Use This Skill

• When your storefront makes 10+ API calls per page load from different services
• When you need to enforce authentication and authorization consistently across all commerce APIs
• When different teams own different services and you need a contract between the frontend and backend
• When you want to apply rate limiting, circuit breakers, or caching without modifying each service
• When you need a single GraphQL schema that spans catalog, inventory, CMS, and personalization data

Prerequisites & Platform Notes

This skill is written for custom/headless storefronts (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

Shopify: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services. WooCommerce: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress. Magento: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

You'll need:

• Node.js 18+ (or adapt to your backend language)
• Redis for caching/queues

Core Instructions

1. Set up Apollo Router for GraphQL Federation

Apollo Federation composes multiple GraphQL subgraphs into a unified supergraph. Each service owns a slice of the schema.

   # Install Apollo Router (the high-performance Rust gateway)
   curl -sSL https://router.apollo.dev/download/nix/latest | sh

   # Install Rover CLI for schema management
   npm install -g @apollo/rover

Define the supergraph config:

   # supergraph.yaml
   federation_version: =2.5.0
   subgraphs:
     catalog:
       routing_url: http://catalog-service:4001/graphql
       schema:
         subgraph_url: http://catalog-service:4001/graphql
     inventory:
       routing_url: http://inventory-service:4002/graphql
       schema:
         subgraph_url: http://inventory-service:4002/graphql
     cart:
       routing_url: http://cart-service:4003/graphql
       schema:
         subgraph_url: http://cart-service:4003/graphql

Compose and run:

   rover supergraph compose --config supergraph.yaml > supergraph.graphql
   ./router --supergraph supergraph.graphql --config router.yaml

2. Define federated subgraph schemas

Each service defines its slice of the schema and can extend types owned by other services:

   # catalog-service/schema.graphql
   type Query {
     product(id: ID!): Product
     products(first: Int, after: String): ProductConnection
   }

   type Product @key(fields: "id") {
     id: ID!
     name: String!
     slug: String!
     description: String
     price: Money!
     images: [Image!]!
   }

   # inventory-service/schema.graphql — extends Product from catalog
   type Product @key(fields: "id") @extends {
     id: ID! @external
     inventory: InventoryStatus!
   }

   type InventoryStatus {
     available: Boolean!
     quantity: Int
     warehouseLocations: [String!]!
   }

The gateway resolves the Product.inventory field by calling the inventory service with the product IDs gathered from the catalog response — automatically, without any client-side orchestration.

3. Build a REST BFF (Backend-for-Frontend) with Fastify

For storefronts that prefer REST over GraphQL:

   import Fastify from 'fastify';
   import {catalogClient} from './services/catalog';
   import {inventoryClient} from './services/inventory';
   import {cmsClient} from './services/cms';

   const app = Fastify({logger: true});

   // Composite endpoint for Product Detail Page
   app.get<{Params: {id: string}}>('/api/pdp/:id', async (request, reply) => {
     const {id} = request.params;
     const customerId = request.headers['x-customer-id'] as string | undefined;

     const [product, inventory, content] = await Promise.allSettled([
       catalogClient.getProduct(id),
       inventoryClient.getStock(id),
       cmsClient.getProductContent(id),
     ]);

     if (product.status === 'rejected') {
       return reply.status(404).send({error: 'Product not found'});
     }

     return {
       product: product.value,
       inventory: inventory.status === 'fulfilled' ? inventory.value : {available: true, quantity: null},
       content: content.status === 'fulfilled' ? content.value : null,
     };
   });

   // Composite endpoint for Cart Page
   app.get<{Params: {cartId: string}}>('/api/cart/:cartId', {
     preHandler: [requireAuth],
   }, async (request, reply) => {
     const cart = await cartClient.getCart(request.params.cartId);
     const productIds = cart.lines.map((l: any) => l.productId);
     const inventoryMap = await inventoryClient.getBulkStock(productIds);

     return {
       ...cart,
       lines: cart.lines.map((line: any) => ({
         ...line,
         inventory: inventoryMap[line.productId] ?? {available: true},
       })),
     };
   });

   await app.listen({port: 3000, host: '0.0.0.0'});

4. Apply authentication at the gateway

The gateway validates JWTs and forwards the decoded identity to subgraphs:

   // middleware/auth.ts
   import {FastifyRequest, FastifyReply} from 'fastify';
   import {verify, JwtPayload} from 'jsonwebtoken';

   export async function requireAuth(request: FastifyRequest, reply: FastifyReply) {
     const token = request.headers.authorization?.replace('Bearer ', '');
     if (!token) return reply.status(401).send({error: 'Authentication required'});

     try {
       const payload = verify(token, process.env.JWT_PUBLIC_KEY!, {algorithms: ['RS256']}) as JwtPayload;
       request.user = {id: payload.sub!, email: payload.email, roles: payload.roles ?? []};
     } catch {
       return reply.status(401).send({error: 'Invalid token'});
     }
   }

   // Apollo Router auth via coprocessor (Rust plugin alternative)
   // router.yaml

   # router.yaml
   authentication:
     router:
       jwt:
         jwks:
           - url: https://your-auth-provider/.well-known/jwks.json

   authorization:
     require_authentication: false  # Allow public queries; subgraphs enforce per-field auth

5. Implement rate limiting and response caching

   // Rate limiting with Redis token bucket
   import {RateLimiterRedis} from 'rate-limiter-flexible';
   import Redis from 'ioredis';

   const redis = new Redis(process.env.REDIS_URL!);

   const rateLimiter = new RateLimiterRedis({
     storeClient: redis,
     keyPrefix: 'rl_gateway',
     points: 100,       // 100 requests
     duration: 60,      // per 60 seconds
     blockDuration: 60, // block for 60s when exceeded
   });

   app.addHook('preHandler', async (request, reply) => {
     const key = request.user?.id ?? request.ip;
     try {
       await rateLimiter.consume(key);
     } catch {
       reply.header('Retry-After', '60');
       return reply.status(429).send({error: 'Too many requests'});
     }
   });

   // Response caching with stale-while-revalidate
   import {fastifyCaching} from '@fastify/caching';
   app.register(fastifyCaching, {privacy: fastifyCaching.privacy.PUBLIC, expiresIn: 60});

6. Add distributed tracing with OpenTelemetry

   // tracing.ts — initialize before importing app modules
   import {NodeSDK} from '@opentelemetry/sdk-node';
   import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-http';
   import {HttpInstrumentation} from '@opentelemetry/instrumentation-http';

   const sdk = new NodeSDK({
     serviceName: 'commerce-gateway',
     traceExporter: new OTLPTraceExporter({url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT}),
     instrumentations: [new HttpInstrumentation()],
   });
   sdk.start();

   // Propagate trace context to downstream services
   // OpenTelemetry auto-injects W3C traceparent headers into all outgoing HTTP requests

Examples

Apollo Router configuration with caching and CORS

# router.yaml
server:
  listen: 0.0.0.0:4000
  cors:
    origins:
      - https://www.mystore.com
      - https://staging.mystore.com

supergraph:
  listen: 0.0.0.0:4000

traffic_shaping:
  router:
    timeout: 30s
  all:
    timeout: 10s
    retry:
      enabled: true
      min_per_sec: 10
      ttl: 10s
      retry_on_http_statuses: [500, 502, 503]

telemetry:
  tracing:
    otlp:
      endpoint: http://otel-collector:4317
      protocol: grpc

Schema stitching for legacy REST services

import {wrapSchema, RenameTypes, FilterTypes} from '@graphql-tools/wrap';
import {fetch} from 'undici';

// Wrap a legacy REST API as a virtual GraphQL subgraph
const legacyProductSchema = buildSchema(`
  type Query {
    legacyProduct(sku: String!): LegacyProduct
  }
  type LegacyProduct {
    sku: String!
    name: String!
    wholesalePrice: Float!
  }
`);

const legacyProductSubschema = {
  schema: legacyProductSchema,
  executor: async ({document, variables}: any) => {
    const sku = variables.sku;
    const res = await fetch(`${process.env.LEGACY_API_URL}/products/${sku}`);
    const product = await res.json();
    return {data: {legacyProduct: product}};
  },
};

Best Practices

• Keep the gateway thin — the gateway handles cross-cutting concerns (auth, rate limiting, caching, tracing); business logic belongs in the services
• Use Apollo Federation for GraphQL — schema stitching works but federation is the standard; it enforces clear ownership and enables schema registry checks in CI
• Set per-service timeouts — a slow inventory service should not hold up a product page; set independent timeouts for each subgraph and use @defer for non-critical data
• Cache at the gateway, not the client — use Cache-Control and Fastify/Apollo caching plugins to serve repeated queries from memory; this reduces load on all downstream services
• Version the gateway API, not the subgraphs — expose /api/v1 and /api/v2 prefixes at the gateway level; individual subgraph schemas evolve independently under federation
• Use health check endpoints for each subgraph — configure the router to poll /health on each service and remove unhealthy subgraphs from routing automatically
• Monitor gateway latency as a system-level SLO — the gateway p99 latency is the ceiling on every user interaction; alert when it exceeds your page performance budget

Common Pitfalls

Related Skills

• @composable-commerce
• @webhook-architecture
• @monitoring-alerting-commerce
• @edge-commerce
• @load-testing-commerce

GraphQL Federation Gateway: Schema Design and Router Configuration

Problem/Feature Description

Meridian Commerce is rebuilding their platform around a composable architecture. They have three backend teams: the Catalog team owns products and categories, the Inventory team owns stock levels and warehouse locations, and the Cart team owns shopping carts and line items. Each team wants to own their GraphQL schema independently, but the storefront needs a single unified GraphQL endpoint so it can query products, inventory, and cart data in one request.

The platform team has been asked to set up a federated GraphQL gateway using industry-standard tooling. They need: (1) a supergraph composition configuration that registers all three subgraphs, (2) subgraph schema files for each service showing how the Product type is shared across services — the Catalog team defines it, the Inventory team extends it with stock data, (3) a production-ready router configuration with proper authentication via JWKS (the company uses Auth0), explicit CORS allowed origins for the storefront (https://shop.meridian.com and https://staging.meridian.com), traffic shaping with independent timeouts, and retry logic.

The gateway should also be configured to propagate the customer's identity headers downstream so subgraphs can perform per-field authorization.

Output Specification

Produce the following configuration and schema files in a gateway/ directory:

• gateway/supergraph.yaml — supergraph composition config listing all three subgraphs
• gateway/router.yaml — Apollo Router configuration (auth, CORS, traffic shaping, header propagation)
• gateway/subgraphs/catalog/schema.graphql — catalog subgraph schema defining the Product type
• gateway/subgraphs/inventory/schema.graphql — inventory subgraph schema extending Product with inventory data
• gateway/subgraphs/cart/schema.graphql — cart subgraph schema

Also produce gateway/SETUP.md documenting the commands needed to: install the required CLI tools, compose the supergraph schema, and start the router.

Commerce Gateway: Distributed Tracing, Performance, and Versioning

Problem/Feature Description

TradeFlow, a B2B commerce platform, has a working API gateway but it is struggling in production: the platform team is getting reports of slow pages, mysterious timeouts, and a critical performance bug — when the storefront fetches a product list with 50 items, the gateway is making 50 individual inventory API calls (one per product). Engineering has also received a complaint from a mobile app team: they added distributed tracing to their service but the gateway is not propagating trace context, making it impossible to see end-to-end traces. Finally, the commerce team is about to release a breaking change to the product API and needs a versioning strategy so the mobile app on the old API version is not disrupted.

A second initiative: the platform has acquired a legacy pricing service that only exposes a REST API. The team wants to include its data in the new unified GraphQL schema without rewriting the legacy system.

The gateway is built in TypeScript. Your task is to address these four concerns: add distributed tracing instrumentation, fix the N+1 query problem in the inventory subgraph, design an API versioning approach for the REST endpoints, and wrap the legacy pricing REST API as a GraphQL subgraph.

Output Specification

Produce a gateway/ directory with the following files:

• gateway/src/tracing.ts — OpenTelemetry setup for the gateway service
• gateway/src/resolvers/inventory-resolver.ts — inventory entity resolver that solves the N+1 performance problem (stub the actual upstream API call)
• gateway/src/subgraphs/pricing/schema.graphql — GraphQL schema for the legacy pricing subgraph
• gateway/src/subgraphs/pricing/executor.ts — executor that integrates the legacy pricing REST API as a virtual GraphQL subgraph
• gateway/src/server.ts — gateway server showing how the REST API versioning strategy is implemented in routing
• gateway/package.json — with all required dependencies
• gateway/DECISIONS.md — documenting: how tracing is initialized relative to other imports, which observability packages are used and the service name chosen, how the N+1 problem is solved, how API versioning is handled at the gateway layer, and which approach integrates the legacy REST API into GraphQL

The code does not need to connect to real services. Use stubs/mocks for the actual upstream HTTP calls. The code should be syntactically correct TypeScript.

Commerce BFF: Product Detail and Cart Aggregation Service

Problem/Feature Description

StyleHub, a mid-sized fashion retailer, is migrating from a monolithic storefront to a composable architecture. Their new backend consists of three independent microservices: a catalog service (product data), an inventory service (stock levels), and a CMS service (rich product descriptions and media). The existing storefront was making 8–12 API calls per page load and engineering has decided to introduce a Backend-for-Frontend layer to consolidate these into single-endpoint responses.

The engineering team wants a TypeScript BFF that handles two critical pages: the Product Detail Page (PDP) and the Cart Page. The PDP aggregates data from all three services — the CMS and inventory are considered "enrichment" data, meaning the page can still render if they are temporarily unavailable. The Cart Page is account-sensitive and must only be accessible to authenticated customers. The team also wants to protect the service from abuse with per-user and per-IP rate limiting backed by Redis, and to cache public responses to reduce load on the microservices. The BFF must log all requests.

Output Specification

Produce a TypeScript implementation of the BFF. The deliverable should be a set of source files in a bff/ directory. Your implementation should include:

• bff/src/server.ts — the main server application with both /api/pdp/:id and /api/cart/:cartId routes
• bff/src/middleware/auth.ts — the JWT authentication middleware
• bff/src/tracing.ts or similar if you add observability (optional)
• bff/package.json — with all required dependencies listed

The actual microservice clients do not need to be implemented (stub them or use placeholder functions). Focus on the BFF structure, middleware wiring, and resilience patterns. Include inline comments explaining any key decisions.

Do not implement a working Redis connection or live JWT verification — use mock/placeholder values where environment variables would normally be required. The code should be syntactically correct and runnable with npm install.

Also produce a bff/DECISIONS.md file documenting: which HTTP framework was chosen and why, how parallel upstream calls are handled, the rate limiting approach and key selection strategy, and the caching strategy.