Integrating GraphQL APIs into a Spring Boot Microservice

Context

Most GraphQL tutorials target the frontend. But on the Boost Mobile MPOS project, I was consuming GraphQL from a Spring Boot backend — acting as a middleware layer between Marketplacer's APIs and the client application.

What I Integrated

6+ Marketplacer GraphQL APIs including:

• Remittances
• Shipments
• Orders
• Commission Packages
• Seller operations

Spring Boot as a GraphQL Consumer

// Using WebClient to call a GraphQL endpoint
WebClient client = WebClient.create(marketplacerBaseUrl);

String query = """
    query {
      orders(first: 10) {
        nodes { id status totalAmount }
      }
    }
    """;

client.post()
    .uri("/graphql")
    .bodyValue(Map.of("query", query))
    .retrieve()
    .bodyToMono(OrderResponse.class);

Handling Base64/CSV Encoded Commission Packages

Commission package assignment was the trickiest part — Marketplacer expected Base64-encoded CSV payloads inside a GraphQL mutation. I built an encoder utility that:

1. Assembled the CSV structure from Java objects
2. Base64-encoded the result
3. Embedded it in the GraphQL mutation body

Observability with MDC Logging

Every request going through the middleware gets a correlation ID via MDC (Mapped Diagnostic Context):

MDC.put("correlationId", UUID.randomUUID().toString());
MDC.put("tenantId", request.getTenantId());
// All downstream logs now carry these fields automatically

This made debugging production issues dramatically faster — especially tracing failures across microservice boundaries.

MapStruct for Clean Data Mapping

With multiple APIs returning different object shapes, MapStruct kept the DTO mapping layer clean and compile-time safe — no runtime reflection surprises.

Lessons Learned

1. GraphQL from the server side requires treating it like any HTTP API — but watch for N+1 query patterns in nested queries.
2. MDC logging is non-negotiable in microservices — add it on day one, not after your first prod incident.
3. Document everything with JavaDoc + Swagger-UI — your future self and teammates will thank you.

Conclusion

Backend GraphQL consumption is an underappreciated skill. Done right with proper observability, mapping layers, and encoding utilities, it becomes a clean and maintainable integration pattern.