Every GraphQL tutorial on subscriptions starts the same way: "First, upgrade your HTTP connection to a WebSocket." Then comes the lecture on graphql-ws, the Sec-WebSocket-Protocol header, ping/pong frames, and the eight ways your connection can die without explanation. You nod through it, ship your subscription, and a month later a customer calls because their corporate firewall blocks wss:// and nothing works. Welcome to 2026, where GraphQL over Server-Sent Events has quietly become the pragmatic alternative that just works.

What SSE Is, And Why It Matters​

Server-Sent Events is a browser-native protocol for server-to-client push. It's been part of HTML5 since the late 2000s and is roughly contemporaneous with WebSockets in browser support (Chrome and Safari shipped EventSource in 2010, Firefox in 2011). And critically:

SSE is just HTTP. The client opens a normal GET request, asks for text/event-stream, and the server writes events to the response body whenever it wants.

That's it. No upgrade handshake. No new protocol. No secondary port. Every single piece of HTTP infrastructure (load balancers, proxies, CDNs, corporate firewalls, VPNs, service meshes) treats SSE like any other long-lived HTTP response. Which, structurally, it is.

GET /graphql/stream HTTP/1.1
Accept: text/event-stream
Cache-Control: no-cache

HTTP/1.1 200 OK
Content-Type: text/event-stream

event: next
data: {"data":{"messageAdded":{"id":"1","text":"hello"}}}

event: next
data: {"data":{"messageAdded":{"id":"2","text":"world"}}}

event: complete
data:

Compare this to WebSockets:

• Client sends Upgrade: websocket + magic Sec-WebSocket-Key header
• Server responds 101 Switching Protocols with a computed handshake key
• Connection is now full-duplex binary framing
• You need ping/pong frames to keep the connection alive
• Half the middleboxes on the internet don't understand it

SSE avoids this entire circus.

The WebSocket Problem Nobody Admits To​

WebSockets work beautifully in Chrome on your office wifi. They break in places you won't discover until it's too late.

Every team that ships WebSocket-based subscriptions eventually gets a support ticket that reads: "subscriptions work fine for me but our enterprise customer in [BigCorp] can't connect." The fix is typically "deploy SSE as a fallback." The better fix is "use SSE from the start."

Meet graphql-sse​

graphql-sse is the reference implementation of the GraphQL over SSE protocol. Same author as graphql-ws. The protocol is short, explicit, and designed to be a drop-in alternative.

Two modes:

Distinct Connections Mode​

Each subscription opens its own SSE stream. Simplest model. Works over both HTTP/1.1 and HTTP/2, though it's really meant for HTTP/2 - on HTTP/1.1 each stream consumes one of the browser's ~6 connections per origin (see below).

GET /graphql/stream?query=subscription+%7BmessageAdded%7BidText%7D%7D HTTP/1.1
Accept: text/event-stream

Events flow until the subscription completes, the client closes, or an error occurs.

Single Connection Mode​

One long-lived SSE connection multiplexes all subscriptions. Better for clients with many subscriptions. Protocol is slightly more involved but still entirely HTTP.

# 1. Reserve a stream token
PUT /graphql/stream HTTP/1.1
# Server responds 201 Created with a token in the body

# 2. Open the SSE stream using that token
GET /graphql/stream?token=ABC HTTP/1.1
Accept: text/event-stream

# 3. Execute operations against the reserved stream
POST /graphql/stream?token=ABC HTTP/1.1
Content-Type: application/json
{ "query": "subscription { ... }" }

# 4. Terminate operations (or DELETE to close the stream)

Both modes are documented in the graphql-sse protocol. Server support varies: GraphQL Yoga (via its @graphql-yoga/plugin-graphql-sse plugin) and Hot Chocolate (built in since v13) expose GraphQL-over-SSE natively on the server. Apollo Server has no first-party SSE transport - its official subscription transport is WebSocket via graphql-ws - so SSE there requires a custom plugin or third-party integration. Browser-side, you typically use the graphql-sse library's own createClient and either consume it directly or wrap it in a custom ApolloLink / urql exchange. There is no first-party Apollo Client subpath for graphql-sse; community packages exist for the link pattern.

Setting It Up on Spring Boot​

Spring's native SSE support via WebFlux makes this fairly painless. @SubscriptionMapping is transport-agnostic, so you do not need a separate resolver for SSE. Since Spring for GraphQL 1.3 (2024) the framework ships a built-in GraphQlSseHandler that serves your existing @SubscriptionMapping methods over text/event-stream; in Spring Boot 3.3+ it is auto-configured alongside the /graphql endpoint (tunable via spring.graphql.http.sse.timeout and spring.graphql.http.sse.keep-alive), so the same subscription resolver is available over BOTH WebSocket and SSE with no extra code.

If you need custom framing or single-connection mode, you can drop down to a controller of your own. Here's the minimal sketch - roughly what the built-in handler does internally, offered as an optional lower-level alternative rather than a requirement:

@RestController
@RequestMapping("/graphql/stream")
public class GraphQlSseController {

    private final ExecutionGraphQlService graphQlService;

    public GraphQlSseController(ExecutionGraphQlService graphQlService) {
        this.graphQlService = graphQlService;
    }

    @GetMapping(produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<ServerSentEvent<Map<String, Object>>> stream(
            @RequestParam String query,
            @RequestParam(required = false) String operationName,
            @RequestParam(required = false) Map<String, Object> variables) {

        ExecutionGraphQlRequest request = new DefaultExecutionGraphQlRequest(
            query, operationName, variables, null, UUID.randomUUID().toString(), null
        );

        return Mono.fromFuture(graphQlService.execute(request).toFuture())
            .flatMapMany(response -> {
                Object data = response.getData();
                if (data instanceof Publisher<?> publisher) {
                    return Flux.from(publisher)
                        .map(event -> ServerSentEvent.<Map<String, Object>>builder()
                            .event("next")
                            .data(Map.of("data", event))
                            .build())
                        .concatWith(Mono.just(
                            ServerSentEvent.<Map<String, Object>>builder()
                                .event("complete")
                                .data(Map.of())
                                .build()
                        ));
                }
                return Flux.just(ServerSentEvent.<Map<String, Object>>builder()
                    .event("next")
                    .data(response.toMap())
                    .build());
            });
    }
}

This is sketchy production code; you'd want authentication, POST support for large queries (GET has URL length limits), error handling, and heartbeat events to keep the connection alive through idle proxies. But it's the right shape.

Flux.interval(Duration.ofSeconds(15))
    .map(i -> ServerSentEvent.<Map<String, Object>>builder()
        .comment("heartbeat")
        .build());

Client-Side: Apollo Using SSE​

There's no first-party Apollo Client subpath for graphql-sse, so you wrap the official graphql-sse client in a custom ApolloLink. The pattern is short and replaces GraphQLWsLink cleanly:

import { ApolloClient, InMemoryCache, split, HttpLink, ApolloLink, Observable } from '@apollo/client';
import { createClient } from 'graphql-sse';
import { getMainDefinition, print } from '@apollo/client/utilities';

const httpLink = new HttpLink({ uri: 'https://api.example.com/graphql' });

const sseClient = createClient({
  url: 'https://api.example.com/graphql/stream',
});

// Minimal Apollo link that delegates to graphql-sse for subscriptions.
const sseLink = new ApolloLink((operation) => new Observable((sink) => {
  return sseClient.subscribe(
    { ...operation, query: print(operation.query) },
    { next: sink.next.bind(sink), error: sink.error.bind(sink), complete: sink.complete.bind(sink) },
  );
}));

const splitLink = split(
  ({ query }) => {
    const def = getMainDefinition(query);
    return def.kind === 'OperationDefinition' && def.operation === 'subscription';
  },
  sseLink,
  httpLink
);

const client = new ApolloClient({
  link: splitLink,
  cache: new InMemoryCache(),
});

The split link routes subscriptions through SSE and everything else through regular HTTP. Your React components that use useSubscription don't change.

The Transport Decision Tree​

You need real-time. Which transport do you pick?

For most GraphQL subscription use cases in 2026, SSE is the right answer. Notifications, chat, live-updating dashboards, prices on a trading screen: all server-to-client pushes with no need for the client to talk back over the same channel.

The Part That's Slightly Worse​

SSE is not objectively better than WebSockets. There are real tradeoffs:

1. No built-in message framing. SSE gives you lines of text. WebSockets give you discrete frames. You build your own boundaries (easy with the graphql-sse protocol).

2. No binary support. SSE is text-only. If you want to stream binary data, you're base64 encoding it or using a separate channel.

3. One-way only. The client cannot push through the SSE stream. If you need a cancel message or a pong-response, you do it with a separate HTTP request.

4. Connection limit in HTTP/1.1. Browsers limit concurrent connections to the same origin (6 typical). If you have 7 SSE streams open, the 7th blocks. HTTP/2 multiplexes, so this is mostly a legacy concern.

5. Debugging is mildly annoying. Chrome DevTools doesn't show SSE streams as nicely as WebSocket frames. You get raw text in the Network tab.

None of these are deal-breakers for typical GraphQL subscription workloads. They matter if you're building something that really wants bidirectional streaming.

The Hidden Bonus: @defer and @stream Come Along​

Remember @defer and @stream? They also produce multi-response streams. And guess what, they work over SSE too. One transport for:

• Queries (single response)
• Mutations (single response)
• Subscriptions (many responses over time)
• Incremental delivery (many responses quickly)

Instead of your server having to juggle HTTP for some things and WebSockets for others, you have one HTTP-based mechanism that handles all four. Simpler topology, fewer failure modes, fewer special cases in your infrastructure.

What This Looks Like in Production​

A team I know migrated their chat app from WebSocket subscriptions to SSE. They wrote up three numbers:

• Zero customer firewall complaints in the 90 days after the switch (they had two per week before)
• 40% reduction in subscription connection errors overall (SSE retries are more predictable)
• One added dependency on the client, one added endpoint on the server

The migration took about a week. They kept the WebSocket endpoint live for six months as a fallback. They removed it last quarter. Nobody noticed.

The Bigger Picture​

The GraphQL community spent years assuming WebSockets were the subscription answer. graphql-ws got all the early ecosystem love. Documentation defaulted to it. Talks at conferences centered on it. And it worked, for a time, for most teams.

What changed is that HTTP itself got better. HTTP/2 multiplexing. HTTP/3 over QUIC. Serverless and edge platforms that all speak HTTP but treat WebSockets as a second-class citizen. The infrastructure moved under our feet while we were busy debating client libraries.

SSE was always waiting. It's been a web standard for over a decade. It runs on any HTTP server. It degrades gracefully. It was available the whole time, we just weren't listening.

If you're greenfield on GraphQL subscriptions today, start with SSE. If you're on WebSocket subscriptions and your infrastructure is holding up, don't rush a migration; there's nothing wrong with WebSockets when they work. But the next time you have to touch that code or debug a subscription mystery in production, give graphql-sse an honest evaluation. The industry has quietly moved on.

This post was streamed over HTTP/3 via your browser, which likely buffered it in a service worker, served it from a CDN, and completely ignored the transport layer. Such is the beauty of boring standards.

Sources​

• graphql-sse on GitHub
• GraphQL over SSE Protocol Specification
• The Guild: GraphQL over SSE
• MDN: Server-Sent Events
• HTML Living Standard: Server-Sent Events
• Apollo Client: Subscription Transport Configuration
• Spring WebFlux: Server-Sent Events

For a decade, GraphQL responses came back as one lump. You asked for a page, you waited for every field to resolve, then the server wrapped it up and sent it over the wire in one envelope. Fast fields waited for slow fields. The whole response moved at the speed of its slowest resolver. Then @defer and @stream arrived to fix exactly that. They've been maturing as a proposal for several years - deliberately, because getting incremental delivery right is genuinely hard - and they're now real enough to use with modern clients and servers. The open question is when they pay off, and both camps have a case.

The Old Problem​

A page loads. The client fires one GraphQL query for everything it needs:

query MovieDetail($id: ID!) {
  movie(id: $id) {
    id
    title            # 2ms from cache
    poster           # 2ms from cache
    cast {           # 800ms from Cast Service
      name
      role
    }
    reviews {        # 2000ms from Review Aggregator, expensive AI sentiment score
      text
      sentiment
      author { name }
    }
  }
}

Total latency: ~2 seconds. But 90% of what the user immediately sees (title, poster, headline info) was ready in 2ms. They're staring at a loading spinner for two seconds because the server is waiting for the reviews aggregator to finish summing up sentiment scores.

The client could break this into three queries. One for the essentials, one for the cast, one for the reviews. Suddenly you're orchestrating requests on the frontend, losing the "one query" simplicity that was half the point of using GraphQL.

@defer and @stream let you keep one query while getting the incremental rendering benefit.

How @defer Works​

The @defer directive says: "this field fragment is lower priority. Send me the rest first, then catch up with this one when it's ready."

query MovieDetail($id: ID!) {
  movie(id: $id) {
    id
    title
    poster
    ... on Movie @defer(label: "slow-stuff") {
      cast { name role }
      reviews {
        text
        sentiment
        author { name }
      }
    }
  }
}

The server now streams two responses:

First response (2ms):

{
  "data": {
    "movie": {
      "id": "42",
      "title": "Inception",
      "poster": "https://..."
    }
  },
  "hasNext": true
}

Second response (2000ms):

{
  "incremental": [{
    "path": ["movie"],
    "label": "slow-stuff",
    "data": {
      "cast": [...],
      "reviews": [...]
    }
  }],
  "hasNext": false
}

The client renders the title and poster at 2ms. The cast and reviews fill in when they're ready. Nothing else changes in your client code except that it processes multiple response payloads instead of one.

How @stream Works​

@stream is for list fields. Instead of waiting for all items, you get items as they're produced.

query Timeline {
  timeline @stream(initialCount: 3) {
    id
    text
    author { name }
  }
}

First response: the first 3 items, returned as soon as they're ready.

{
  "data": {
    "timeline": [
      { "id": "1", "text": "...", "author": {...} },
      { "id": "2", "text": "...", "author": {...} },
      { "id": "3", "text": "...", "author": {...} }
    ]
  },
  "hasNext": true
}

Subsequent responses: each additional item as it arrives.

{
  "incremental": [{
    "items": [
      { "id": "4", "text": "...", "author": {...} }
    ],
    "path": ["timeline", 3]
  }],
  "hasNext": true
}

This is useful when your list has a slow tail. The first few items load fast, but item 4 requires a call to a flaky partner API. Instead of waiting for the whole list, the client renders what it has and tops up as the rest trickles in.

The Transport Layer: multipart/mixed​

A GraphQL request returning multiple payloads can't use a standard single-response HTTP exchange. Rather than invent something new, the spec reached for multipart/mixed, a proven content type that has carried multi-part HTTP payloads for decades. Reusing a battle-tested standard instead of inventing a bespoke one is a pragmatic, interoperable choice.

POST /graphql HTTP/1.1
Content-Type: application/json
Accept: multipart/mixed; incrementalSpec=v0.2, application/json

The server responds:

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary="-"

---
Content-Type: application/json; charset=utf-8

{"data":{"movie":{"id":"42","title":"Inception","poster":"..."}}, "hasNext":true}
---
Content-Type: application/json; charset=utf-8

{"incremental":[{"path":["movie"],"data":{"cast":[...]}}],"hasNext":false}
-----

Each chunk is a separate JSON payload, separated by the boundary string. The connection stays open until hasNext is false.

Alternative transports exist. Apollo's docs mention Server-Sent Events and WebSocket. In practice, multipart/mixed is the one the spec blessed, and it's what Apollo Client, Relay, and urql support natively.

Server-Side: graphql-java and Spring​

graphql-java's support for incremental delivery landed in 22.x. Spring GraphQL exposes it, but it's still experimental territory in 2026. The mental model: your resolver returns a CompletableFuture for deferred fields, and the framework handles the chunked response.

@Controller
public class MovieController {

    private final MovieService movieService;
    private final ReviewService reviewService;

    public MovieController(MovieService movieService, ReviewService reviewService) {
        this.movieService = movieService;
        this.reviewService = reviewService;
    }

    @QueryMapping
    public Movie movie(@Argument Long id) {
        return movieService.findById(id);
    }

    // Deferred: returned async, sent in a second chunk
    @SchemaMapping
    public CompletableFuture<List<Review>> reviews(Movie movie) {
        return reviewService.loadReviewsAsync(movie.id());
    }
}

The framework decides whether to defer based on the client's query. If the client uses @defer on the reviews field, the response streams in chunks. If they don't, the response is single-envelope as always. Your code doesn't branch based on client behavior.

Client-Side: Apollo and Relay​

Apollo Client (v3.7+) supports @defer transparently. Your component hooks work the same way; the UI renders deferred fields as they arrive.

const MOVIE_QUERY = gql`
  query MovieDetail($id: ID!) {
    movie(id: $id) {
      id
      title
      poster
      ... on Movie @defer {
        cast { name role }
        reviews { text author { name } }
      }
    }
  }
`;

function MovieDetail({ id }) {
  const { data, loading } = useQuery(MOVIE_QUERY, { variables: { id } });

  if (loading && !data) return <Spinner />;

  return (
    <div>
      <h1>{data.movie.title}</h1>
      <img src={data.movie.poster} />
      {data.movie.cast
        ? <CastList cast={data.movie.cast} />
        : <Skeleton />}
      {data.movie.reviews
        ? <Reviews reviews={data.movie.reviews} />
        : <Skeleton />}
    </div>
  );
}

The first render has title and poster. Subsequent renders light up cast and reviews independently as chunks arrive. No manual state machine, no coordinating multiple queries. Just fragments with @defer on them.

Relay has similar support, tightly integrated with React Suspense. The ergonomics are good. The ceremony is minimal.

The "It's Overkill" Argument​

WunderGraph has a post arguing that @defer and @stream are overengineered solutions to a problem most teams don't have. The argument boils down to:

1. Most queries don't need it. For a typical page load, the extra transport complexity buys you 100-200ms of perceived latency improvement that a loading skeleton already handles.

2. HTTP/2 already does multiplexing. You can fire multiple GraphQL queries in parallel and get most of the same benefit with standard request/response semantics.

3. Client support is patchy. A lot of HTTP clients, caching layers, proxies, and API gateways don't understand multipart/mixed. You'll find out at the worst possible time.

4. It complicates caching. Your CDN sees a long-lived connection with multipart content instead of a cacheable response. Full-response caching is out the window.

5. The spec took its time. The working group worked through the details carefully over several years, and teams that wanted incremental delivery sooner built interim workarounds that still hold up fine.

All of these points are legitimate. @defer and @stream are not a free win. They're a tradeoff, and the tradeoff only pays off in specific scenarios.

When To Actually Use @defer​

When To Actually Use @stream​

@stream is narrower. It's useful when:

• Lists are long
• Tail items are slow to produce
• You want the user to see the top of the list before the bottom is ready
• Infinite-scroll style UIs

It's misused when:

• Lists are short (10 items? just return them)
• You want traditional pagination (use a connection, don't stream)
• The whole list comes from a single DB query (streaming doesn't save anything here)

What This Means Right Now​

If you're using modern Apollo Client or Relay against a graphql-java 22+ server, you can experiment with @defer today. Note that graphql-java 22 added @defer only - @stream came in a later release - so check your server version against what you actually want to use. Find one or two queries where you're blocking the whole page on one slow field. Add a @defer fragment. Measure the change.

The most production-mature @defer deployment story today is Apollo Router. It shipped @defer support at v1.0 (September 2022) with entity-based @defer initially in preview, and later brought @defer to GA (support requires Router v1.8.0+). It can also synthesize entity-based @defer even when individual subgraphs don't natively support it.

If the numbers are good, great. Adopt it where it helps. If the numbers are marginal, you've learned something: your bottleneck wasn't the thing you thought it was.

What @defer and @stream are absolutely not: a replacement for good query design. If you're using @defer to mask the fact that your schema has a field that takes 2 seconds to resolve, fix the resolver. Incremental delivery is not a performance strategy. It's a perceived-performance strategy. Real performance fixes still require boring work like:

• Adding DataLoaders for N+1
• Caching expensive computations
• Bounding list returns
• Indexing your database

@defer and @stream are nice polish on top of a well-built API. They are not glue for a broken one.

The Verdict​

With incremental delivery, GraphQL brings the streaming benefits of HTTP chunked encoding and SSE into a schema-aware, single-query model - the kind of structured approach it's known for. Be clear-eyed about the maturity, though: incremental delivery is a Stage 2 (Draft) proposal, still experimental and not yet merged into the main GraphQL spec. The very fact that the wire format is versioned (incrementalSpec=v0.2, used by graphql-js v17 alphas and Apollo Server 5) is a sign it is not final and can still change. Treat production use as early-adopter territory, not a settled standard. Client support is improving, server support is maturing, and the DX is fine, but the blast radius of adopting it is larger than a typical directive: transport headers, client capabilities, caching behavior, and proxy compatibility all shift.

Use it where the payoff is real and the environment supports it. Skip it where the complexity outweighs the gain. This is a tool for your toolbox, not a default to turn on everywhere.

This post was written incrementally. The first draft was title, hook, and conclusion. The middle chunks came in one at a time. Each chunk had hasNext: true until the author remembered coffee existed.

Sources​

• GraphQL Working Group: DeferStream RFC
• Apollo Client: @defer Documentation
• WunderGraph: GraphQL's @defer and @stream Directives are overkill
• Altair GraphQL Client: Incremental Delivery
• Unleashing Incremental Data Delivery in GraphQL
• Hive: Subscription and Incremental Delivery Usage Reporting

Your P99 just spiked from 180ms to 2.4 seconds. Your supergraph has eight subgraphs. Each subgraph team insists they're healthy. The dashboards on each individual service are green. The router is sweating. Somebody is lying. Without proper tracing across the federation, you're going to spend the next three hours on a war room Zoom call doing forensics with timestamps.

The Problem With Federated Observability​

A single GraphQL request in a federated architecture is not a single HTTP call. It's a dance:

Client
   ↓
Router (plans)
   ↓
Subgraph A (users) ─→ returns partial result
   ↓
Subgraph B (orders) ─→ needs data from A, waits, then queries
   ↓
Subgraph C (inventory) ─→ parallel with B
   ↓
Router (merges)
   ↓
Client

Each arrow is a hop. Each hop can fail, slow down, or return garbage. When something goes wrong, "which service was slow" becomes a question you can only answer if every service and the router share a correlation ID and export their spans to the same tracing backend.

Without that: you are staring at a stopwatch across eight dashboards and eyeballing "which one looks suspicious." This is not a debugging strategy. It's a cry for help.

Why OpenTelemetry Won​

Three years ago, you had Jaeger, Zipkin, Datadog's custom format, New Relic's custom format, Honeycomb's beeline, and a dozen vendor-specific libraries. Each one had its own SDK, its own context propagation rules, and its own way to add custom spans. Switching backends meant rewriting your instrumentation.

OpenTelemetry ended that war. It's now the CNCF-blessed standard, and as of 2026, every major tracing backend speaks OTLP (OpenTelemetry Protocol). Your instrumentation code is vendor-neutral. You export to Jaeger, Honeycomb, Datadog, Grafana Tempo, or New Relic by changing an endpoint URL.

For GraphQL federation specifically, OpenTelemetry is no longer optional. It's the only reasonable way to trace a request that hops through a router and three subgraphs.

The Apollo Router: First-Class OpenTelemetry​

Apollo Router (v2.x) ships OpenTelemetry support in the base image. You configure it via YAML and span export just works:

# router.yaml
telemetry:
  instrumentation:
    spans:
      mode: spec_compliant
  exporters:
    tracing:
      propagation:
        trace_context: true
        baggage: true
      otlp:
        enabled: true
        endpoint: http://otel-collector:4317
        protocol: grpc

Three things are happening here:

1. Propagation - The router reads and writes W3C trace context headers, so a client-side trace continues through the router and into subgraphs.
2. Instrumentation - The router emits its own spans for query planning, query execution, and each subgraph fetch.
3. Export - Spans go to an OpenTelemetry Collector, which fans out to your actual backend.

The router will automatically add HTTP headers to subgraph requests that let subgraphs continue the trace. If your subgraphs are OpenTelemetry-instrumented, they'll add their spans to the same trace ID.

Wiring Up a Spring GraphQL Subgraph​

Spring Boot's OpenTelemetry integration is in good shape in 2026. The autoconfigured starter covers most of what you need:

<!-- pom.xml -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-spring-boot-starter</artifactId>
</dependency>

# application.yaml
otel:
  service:
    name: users-subgraph
  exporter:
    otlp:
      endpoint: http://otel-collector:4317
  traces:
    exporter: otlp
  metrics:
    exporter: otlp
  logs:
    exporter: otlp
  propagators: tracecontext,baggage

Out of the box, this gives you:

• HTTP server spans for every inbound GraphQL request
• JDBC spans for every database query
• Outbound HTTP client spans for every RestTemplate or WebClient call
• Automatic trace context propagation through @Async boundaries

What's missing: GraphQL-aware spans. A Spring GraphQL request shows up as an HTTP POST to /graphql in your trace, which is about as useful as "something happened." You want a span per field resolver, a span per DataLoader batch, and a span that names the operation.

Adding GraphQL-Native Spans​

Spring GraphQL lets you intercept execution via GraphQlInterceptor and DataFetcherExceptionResolver. Combine those with a custom Instrumentation (from graphql-java) and you get trace visibility that actually tells you something.

@Component
public class GraphQlTracingInstrumentation extends SimplePerformantInstrumentation {

    private final Tracer tracer;

    public GraphQlTracingInstrumentation(OpenTelemetry otel) {
        this.tracer = otel.getTracer("graphql");
    }

    @Override
    public InstrumentationContext<ExecutionResult> beginExecution(
            InstrumentationExecutionParameters params) {

        String operationName = params.getOperation() != null
            ? params.getOperation()
            : "anonymous";

        Span span = tracer.spanBuilder("graphql.execute " + operationName)
            .setSpanKind(SpanKind.SERVER)
            .setAttribute("graphql.operation.name", operationName)
            .setAttribute("graphql.document", truncate(params.getQuery(), 1000))
            .startSpan();

        try (Scope ignored = span.makeCurrent()) {
            return new InstrumentationContext<>() {
                @Override
                public void onDispatched(CompletableFuture<ExecutionResult> future) {}

                @Override
                public void onCompleted(ExecutionResult result, Throwable t) {
                    if (t != null) {
                        span.recordException(t);
                        span.setStatus(StatusCode.ERROR);
                    }
                    if (result != null && !result.getErrors().isEmpty()) {
                        span.setAttribute("graphql.errors.count",
                            result.getErrors().size());
                        span.setStatus(StatusCode.ERROR, "graphql errors");
                    }
                    span.end();
                }
            };
        }
    }

    @Override
    public InstrumentationContext<Object> beginFieldFetch(
            InstrumentationFieldFetchParameters params) {

        String fieldPath = params.getEnvironment()
            .getExecutionStepInfo().getPath().toString();

        Span span = tracer.spanBuilder("graphql.field " + fieldPath)
            .setAttribute("graphql.field.path", fieldPath)
            .setAttribute("graphql.field.type",
                params.getEnvironment().getFieldType().toString())
            .startSpan();

        return new InstrumentationContext<>() {
            @Override
            public void onDispatched(CompletableFuture<Object> future) {}

            @Override
            public void onCompleted(Object result, Throwable t) {
                if (t != null) {
                    span.recordException(t);
                    span.setStatus(StatusCode.ERROR);
                }
                span.end();
            }
        };
    }
}

Register it in your Spring GraphQL config:

@Configuration
public class GraphQlConfig {

    @Bean
    public GraphQlSourceBuilderCustomizer customizer(
            GraphQlTracingInstrumentation instrumentation) {
        return builder -> builder.configureGraphQl(graphQl ->
            graphQl.instrumentation(instrumentation)
        );
    }
}

Now each GraphQL request produces a tree of spans you can actually read:

POST /graphql                              (HTTP server span from auto-instrumentation)
  └── graphql.execute GetUserProfile       (from our instrumentation)
        ├── graphql.field /user             (field span)
        │     └── SELECT * FROM users       (JDBC span from auto-instrumentation)
        ├── graphql.field /user/orders      (field span)
        │     └── GET /orders?userId=123    (HTTP client span)
        └── graphql.field /user/preferences (field span)
              └── SELECT * FROM prefs       (JDBC span)

The Magic Moment: Seeing Cross-Subgraph Latency​

Here's what federated tracing actually gets you. A slow query comes in, you find the trace, and you see:

[root trace - 2.4s total]
  router.plan_query                30ms
  router.subgraph.fetch users      45ms   ← fast
  router.subgraph.fetch orders    2280ms  ← oh no
    HTTP POST /graphql             2275ms
      graphql.execute GetOrders    2270ms
        graphql.field /orders       12ms
        graphql.field /orders/items 8ms
          SELECT items WHERE ...  2250ms  ← the actual villain
  router.merge_response             15ms

Without federation tracing, you'd see "the router took 2.4 seconds" and stop. With federation tracing, you see "the orders subgraph's items query hit a missing database index." One is a line item on a Jira ticket. The other is a three-hour debugging session.

The OpenTelemetry Collector: Don't Skip This​

Here's the mistake every team makes on first OpenTelemetry rollout: they point every service directly at their tracing backend. This works on day one. It explodes on day thirty when:

• Every service holds its own connection to the backend
• Sampling decisions are made inconsistently
• You need to add a new tag retroactively (impossible - already sent)
• You want to switch backends

The OpenTelemetry Collector solves all of this. It runs as a sidecar or daemonset in your cluster, receives OTLP from your services, and forwards to one or more backends. Between "receive" and "forward" you can transform, sample, enrich, or route.

# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    timeout: 10s
  resource:
    attributes:
      - key: deployment.environment
        value: production
        action: insert
  tail_sampling:
    decision_wait: 10s
    policies:
      - name: errors
        type: status_code
        status_code:
          status_codes: [ERROR]
      - name: slow-requests
        type: latency
        latency:
          threshold_ms: 500
      - name: sample-rest
        type: probabilistic
        probabilistic:
          sampling_percentage: 5

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, tail_sampling, batch]
      exporters: [otlp/tempo]

The tail sampler keeps 100% of errors, 100% of slow requests, and 5% of normal traffic. That's a 95% cost reduction with almost no signal loss. Your SRE team will buy you coffee.

Apollo Router + OpenTelemetry in Practice​

A few things the Apollo docs will tell you but are worth emphasizing:

Operation Name is a Trace Attribute​

Make sure every client sends a named operation. query GetUserProfile beats query { ... } because your traces become groupable. When you look at "latency by operation" charts, anonymous queries all merge into one bucket you can't debug.

Subgraph Request Headers Propagate​

The router by default adds traceparent and tracestate headers to subgraph requests. Your subgraphs need to be configured to read those headers (OpenTelemetry auto-instrumentation does this). Miss the config, and your subgraph starts a new trace instead of continuing the existing one, fragmenting the view.

Error Traces Are The Highest-Signal Traces​

Always sample 100% of errored requests. They're rare, they're tiny in aggregate, and they're the single highest-value data you have when something breaks. A tail sampler with an error policy is table stakes.

Metrics Matter Too​

OpenTelemetry isn't just traces. Apollo Router exports metrics for query planning duration, subgraph request counts, cache hit rates, and more. Wire these into Prometheus or a Grafana Cloud endpoint. Your "is the router healthy" dashboard wants these numbers.

Common Gotchas​

What Your Dashboard Should Look Like​

A good federated tracing setup gives you, at minimum:

1. Per-operation latency percentiles. p50, p95, p99 by operation name.
2. Subgraph fetch latency heatmap. Rows = subgraphs, columns = time, color = latency.
3. Error rate by subgraph. Who's failing, and how often.
4. Slow trace explorer. Top 50 slowest traces in the last hour, clickable.
5. Query plan duration. Is the router spending too long planning?

Grafana, Honeycomb, Datadog, and Jaeger all have templates for this. Use one. Don't build from scratch unless you really want to.

The Honest Operational Truth​

Federated tracing is a solved problem in 2026 but only if you set it up properly. The tools exist. The standards exist. The instrumentation libraries exist. What's missing, usually, is the discipline to wire them up before you need them.

Teams that invest in tracing early never regret it. Teams that skip it eventually spend a week doing observability work at 3 AM because a customer noticed something before their monitoring did.

Do it now. While everything is green. Your future on-call self will thank you. And when the P99 spikes next Tuesday at 11 PM, you'll click one link in Slack, see the subgraph that's lying, and be back in bed in fifteen minutes instead of three hours.

This post was traced through four drafts, two editing sessions, and one coffee break. The coffee was the slowest span.

Sources​

• Apollo Router Telemetry Configuration
• OpenTelemetry Documentation
• OneUptime: How to Instrument Apollo GraphQL Server with OpenTelemetry for Federated Graph Trace Visibility
• OpenTelemetry Spring Boot Starter
• W3C Trace Context Specification
• OpenTelemetry Collector Documentation
• Apollo: Evolving the Federated GraphQL Platform at Netflix

Two camps. One schema. Endless arguments on Twitter. Every Java GraphQL project, within the first week, has the same meeting: should we write the schema first in SDL, or should we write Java classes and let the schema fall out of them? Both camps are convinced the other is doing it wrong. Both are partially right. Here's the honest breakdown, the actual tradeoffs, and what the 2026 Java ecosystem looks like when you stop arguing and pick one.

The Two Philosophies​

Schema-first starts with .graphqls files.

# schema.graphqls
type Movie {
  id: ID!
  title: String!
  releaseYear: Int
  director: Director
}

type Director {
  id: ID!
  name: String!
  movies: [Movie!]!
}

type Query {
  movie(id: ID!): Movie
  movies(limit: Int = 10): [Movie!]!
}

Then you write Java code that implements whatever the SDL promised. The schema is the source of truth. Your classes are the implementation detail.

Code-first starts with Java classes. Annotation specifics depend on the library; SPQR (the dominant Java code-first option) infers most of the schema from your types and uses @GraphQLApi, @GraphQLQuery, @GraphQLArgument, @GraphQLNonNull, and @GraphQLIgnore for the cases inference can't cover:

@GraphQLApi
public class MovieService {

    private final MovieRepository repo;

    @GraphQLQuery(name = "movie")
    public Movie movie(@GraphQLArgument(name = "id") @GraphQLNonNull String id) {
        return repo.findById(id);
    }
}

public record Movie(
    @GraphQLNonNull String id,
    @GraphQLNonNull String title,
    Integer releaseYear,
    Director director
) {}

The framework introspects your classes and generates the schema at startup. Your classes are the source of truth. The SDL is the byproduct.

Both approaches produce the same running API. The difference is where the contract lives.

The Java Landscape (April 2026)​

Which approach do the major Java frameworks actually support?

The Java ecosystem leans schema-first. Kotlin slightly favors code-first, largely because graphql-kotlin has been very good at it. Python and JavaScript are mixed. Go is mostly code-first via gqlgen.

The Case For Schema-First​

Let's start with the dominant approach and its genuine strengths.

Your Schema Is Readable By Non-Java Devs​

The frontend team does not want to read your Java classes to understand what fields they can query. Your product manager does not want to parse @GraphQLNonNull to know if a field is required. Your partner team integrating with your API does not run a Java compiler before their meeting.

SDL is the lingua franca. Everyone who touches GraphQL reads SDL. Nobody is forced to read your annotation dialect.

Contract Before Code​

Schema-first forces design before implementation. You can't scaffold a type without thinking about it because the SDL is right there, staring at you. In code-first, you can accidentally expose a whole internal model because your User class has a passwordHash field and you forgot to annotate it with @GraphQLIgnore.

// Code-first danger zone
public class User {

    private String username;

    // Oops: meant to be hidden, but SPQR's default visibility maps
    // every public/getter-exposed field. Without @GraphQLIgnore here
    // (and with a public getter), this leaks into the schema.
    private String passwordHash;
}

Tooling Bonanza​

Schema-first gets the entire GraphQL tooling ecosystem for free. IDE plugins, linters, schema diff tools, codegen for every client language, and mock servers all expect SDL as input. If your source of truth is Java annotations, you have to emit SDL first before the tools work, which means your build pipeline gets a "generate SDL" step that's always slightly out of sync with reality.

The Federation Story Is Cleaner​

Apollo Federation directives (@key, @external, @requires, @provides) were designed for SDL. You can express them in code-first frameworks, but it's awkward. In schema-first, they're just part of the schema.

type Movie @key(fields: "id") {
  id: ID!
  title: String!
}

That's it. No annotation gymnastics.

The Case For Code-First​

Now the defense of the minority position. Code-first has real advantages that schema-first fans tend to dismiss.

The Single Source of Truth Problem​

In schema-first, you have two things that must stay aligned: your SDL and your Java code. If they drift, the compiler won't save you.

# schema.graphqls
type Movie {
  id: ID!
  title: String!
  rating: Float
}

public record Movie(Long id, String title /* where's rating? */) {}

This compiles. It also runs. It just returns null for rating because Spring GraphQL defaults unknown fields to null when no resolver matches. You find out in QA. Or in prod. In code-first, adding rating to the schema requires adding it to the class. The compiler enforces it.

Refactoring Actually Works​

Rename releaseYear to releasedAt in schema-first, and your IDE refactor tool doesn't know the SDL exists. You get a broken app at runtime. You grep the SDL, fix it, then grep again for resolver method names, fix them, run the tests, fix the mocks, fix the tests that mocked the old field, and so on. In code-first, you right-click, rename, and IntelliJ handles it.

Custom Scalars Are Less Painful​

In schema-first, custom scalars live in your SDL as scalar Date, and you register them at runtime. If you forget to register one, you get an "Unknown type 'Date'" error at startup. In code-first, the framework sees your LocalDate return type and maps it automatically (given proper configuration). One less thing to synchronize.

Polymorphism Is Easier When The Source Is Code​

If your domain model has a sealed hierarchy, code-first can sometimes reflect it directly into a GraphQL union or interface. Schema-first requires you to hand-translate the hierarchy into SDL, then register TypeResolver implementations that decide at runtime which concrete type a value is.

// Code-first (graphql-kotlin / SPQR style)
sealed interface PaymentMethod permits CreditCard, BankTransfer, Crypto {}

record CreditCard(String last4, String brand) implements PaymentMethod {}
record BankTransfer(String iban, String swift) implements PaymentMethod {}
record Crypto(String chain, String address) implements PaymentMethod {}

The framework can emit:

union PaymentMethod = CreditCard | BankTransfer | Crypto

And automatically wire the TypeResolver. In schema-first, you write the union in SDL, then write a TypeResolver manually, and if you add a fourth payment method, you touch three files instead of one.

The Middle Path: Schema-First With Codegen​

Here's the approach most pragmatic Java teams in 2026 have settled on:

1. Write SDL. It's the contract. Frontend teams read it. Federation works. Tooling works.
2. Generate Java types from the SDL. Now the compiler knows about your schema.
3. Hand-write the resolver logic. This is where your business code lives.

DGS codegen does this natively. Spring GraphQL users reach for graphql-codegen or graphql-java-codegen. The generated types sit in a generated/ directory, never hand-edited, always in sync with the SDL.

schema.graphqls           ← source of truth
    ↓ codegen
generated/Movie.java      ← auto-generated type
generated/MovieResolver.java  ← auto-generated interface
    ↓ you implement
MovieResolverImpl.java    ← your business logic

This is close to what code-first frameworks produce, except the direction of the arrow is reversed: SDL generates code, not the other way around. For most Java teams, this is the right answer.

The DGS Perspective​

DGS is schema-first and strongly opinionated about it. Their codegen is tight, the developer loop is fast, and the generated types look like records you'd have written yourself. Netflix runs their entire federated graph this way, and it clearly works.

# schema.graphqls
type Movie {
  id: ID!
  title: String!
  releaseYear: Int
}

// Generated by DGS codegen
public class Movie {
    private String id;
    private String title;
    private Integer releaseYear;
    // ... getters, builders, etc.
}

// You write this
@DgsComponent
public class MovieFetcher {

    @DgsQuery
    public Movie movie(@InputArgument String id) {
        return movieService.findById(id);
    }
}

The generated types mean your resolver is strongly typed against the schema. Add a field in SDL, regenerate, and the compiler tells you which resolvers need an update.

The Spring GraphQL Perspective​

Spring GraphQL is also schema-first, but less opinionated about codegen. You can use generated types if you want. You can also return plain Java records, and Spring GraphQL will map fields by reflection.

// No codegen
public record Movie(Long id, String title, Integer releaseYear) {}

@Controller
public class MovieController {

    @QueryMapping
    public Movie movie(@Argument Long id) {
        return movieService.findById(id);
    }
}

Spring GraphQL looks at the query, asks "does this record have a title field?", finds the accessor, and returns it. Simple and flexible. The tradeoff: if your schema has a field your record doesn't, Spring GraphQL resolves to null without complaint.

This is the most "just Java, just Spring" way to build a GraphQL API, and many teams ship it this way for years. It's also the approach most likely to let schema drift sneak into production, because nothing checks that your records match the SDL. The answer is test coverage, not more annotations.

The Code-First Corner: SPQR and graphql-kotlin​

If you want to go full code-first in Java land, the tool to know is SPQR. It introspects your Java classes, handles generics via type literals, and emits SDL at startup.

@GraphQLApi
public class MovieService {

    @GraphQLQuery(name = "movie")
    public Movie findMovie(@GraphQLArgument(name = "id") Long id) {
        return movieRepository.findById(id);
    }
}

// Startup:
GraphQLSchema schema = new GraphQLSchemaGenerator()
    .withOperationsFromSingleton(new MovieService())
    .generate();

SPQR has a loyal following and is legitimately good. But the Spring GraphQL and DGS momentum has mostly pulled the Java ecosystem toward schema-first, and SPQR fills a niche rather than the mainstream.

In Kotlin-land, graphql-kotlin is the bigger story. Kotlin's sealed classes, data classes, and coroutines map cleanly onto GraphQL concepts, and code-first in Kotlin feels more natural than in Java.

How To Actually Decide​

Honest advice, based on what actually works in practice:

The Meta-Point​

Here's the part nobody says at the end of the argument: both approaches are fine. Teams that pick schema-first ship successful products. Teams that pick code-first ship successful products. Teams that pick hybrid ship successful products.

The failures that actually happen in production are not caused by the choice between SDL-first and Java-first. They're caused by:

• Unbounded list fields that return 50,000 rows
• Non-null fields that get set to null when a service goes down
• Missing DataLoaders causing N+1
• No query cost analysis letting clients DoS the server

These issues are equally possible in both worlds. The SDL-vs-code debate is architecture theater. The real question is whether your schema, however you authored it, is resilient, bounded, and documented.

Pick an approach. Stick with it. Spend the saved argument energy on field nullability.

This post was written in neither schema-first nor code-first style. It was written in Markdown. The author considers himself beyond such squabbles.

Sources​

• Spring for GraphQL Reference
• DGS Framework: Generating Code from Schema
• SPQR: GraphQL Schema Publisher & Query Resolver
• graphql-kotlin Documentation
• GraphQL Code Generator
• graphql-java-codegen
• Apollo Federation Subgraph Specification

For six years, the Java GraphQL world had two doors. Door One: Netflix DGS, born at a company whose entire product is one giant graph. Door Two: Spring GraphQL, blessed by the Spring team itself. Pick a door, write your code, and pray you never had to switch. Then somebody at Netflix and somebody at VMware had coffee, and the doors got knocked down. Here's what actually happened, what it means for your codebase, and whether you should care.

Two Frameworks, Same Engine​

First, the thing nobody tells newcomers: both DGS and Spring GraphQL sit on top of the same execution engine.

Your annotated Spring controllers
Your @DgsComponent classes
           ↓↓
   Spring GraphQL / DGS
           ↓↓
      graphql-java
           ↓↓
       Your schema

Underneath, it's graphql-java running the actual query. The frameworks are two different layers of Java ergonomics piled on top. Different annotations, different lifecycles, different ways to wire a DataLoader. But the query parsing, execution, and subscription plumbing is the same code underneath.

This is important because it's why the integration was even possible. They weren't arguing about the engine. They were arguing about the steering wheel.

A Brief History of the Two Doors​

DGS (Domain Graph Service) shipped from Netflix in February 2021. Netflix had been running graphql-java at scale for years and wanted a more opinionated developer experience. They built annotations like @DgsQuery, @DgsData, @DgsDataLoader, and @DgsEntityFetcher. They added codegen. They baked in federation support. It felt like a framework, not a library.

Spring GraphQL shipped in 2022 from the Spring team. It arrived with @QueryMapping, @MutationMapping, @SchemaMapping, @BatchMapping. It looked like the rest of Spring: same lifecycle, same conventions, same @Controller mental model. It was less opinionated than DGS, more integrated with Spring Security and Spring WebFlux.

For roughly two years (Spring GraphQL 1.0 in May 2022 to DGS 8.5.0 with first-class Spring GraphQL integration in March 2024), picking one meant you couldn't use the other.

Both work. Both are production-grade. But for years, adopting one was a bet, and the bets diverged.

The Merger, or "Integration," or Whatever We're Calling It​

The Netflix blog post A Tale of Two Frameworks tells the story. Boiled down: DGS now runs on top of Spring GraphQL.

This is not "DGS is deprecated." This is not "Spring GraphQL absorbed DGS." This is "DGS keeps its annotations and developer experience, but the request handling, transport, and wiring happen inside Spring GraphQL." The DGS Schema Provider is responsible for wiring up data fetchers for both programming models simultaneously.

The elegant outcome: two teams stop building the same wheel twice, and users stop having to pick a door.

Mixing the Two: A Concrete Example​

Here's what was impossible in 2022 and is table stakes now:

// DGS-style for the parts where DGS feels right
@DgsComponent
public class MovieFetcher {

    private final MovieService movieService;

    public MovieFetcher(MovieService movieService) {
        this.movieService = movieService;
    }

    @DgsQuery
    public Movie movie(@InputArgument Long id) {
        return movieService.findById(id);
    }

    @DgsEntityFetcher(name = "Movie")
    public Movie resolveMovieEntity(Map<String, Object> values) {
        return movieService.findById(Long.valueOf((String) values.get("id")));
    }
}

// Spring GraphQL style for the parts where it feels right
@Controller
public class MovieController {

    private final ReviewService reviewService;

    public MovieController(ReviewService reviewService) {
        this.reviewService = reviewService;
    }

    @BatchMapping(typeName = "Movie")
    public Map<Movie, List<Review>> reviews(List<Movie> movies) {
        return reviewService.findByMovies(movies);
    }

    @SubscriptionMapping
    public Flux<Rating> ratingUpdates(@Argument Long movieId) {
        return reviewService.streamRatings(movieId);
    }
}

Same schema. Same app. One process. One port. Both frameworks coexist because underneath, they're writing data fetchers into the same graphql-java GraphQL instance.

This matters for teams with legacy DGS code who want to start using @BatchMapping without a rewrite. It matters for Spring shops that inherit a DGS module and don't want to throw it away.

Worth flagging: Netflix's own DGS documentation recommends sticking with one programming model in steady-state code. The integration calls mixing "technically possible" rather than "officially endorsed," and some advanced features (notably DataLoader Scheduled Dispatch) do not work cleanly across both styles in the same app. Treat the mixing pattern as a migration tool, not a permanent architecture.

The Version Map (As of June 2026)​

Keeping versions straight has been a whole subplot of the Java GraphQL story. Here's where things actually land:

The Opinionated vs. Unopinionated Divide​

Now for the thing everyone really wants to know: which one should you use for a greenfield project in 2026?

DGS and Spring GraphQL make different bets about what your team values.

DGS: Opinionated By Design​

DGS has conventions. The codegen output has a shape. The annotations have expectations. If you pick up a DGS codebase from another team, you can mostly predict where things are.

DGS leans into:

• Code generation as a first-class workflow (schema-first from day one)
• Federation with first-class directives
• Entity fetchers for subgraph membership
• DgsQueryExecutor for unit tests that are actually easy to write

Spring GraphQL: Conventions Over Opinions​

Spring GraphQL is lighter. It plugs into the Spring way: @Controller, @Component, @ConditionalOnMissingBean. If you know Spring, you already know where things go.

Spring GraphQL leans into:

• Less framework, more library
• Tight integration with Spring Security, Spring Data, WebFlux
• GraphQlTester that composes naturally with @SpringBootTest
• No codegen by default (bring your own)

The Decision Tree​

Migrating: It's Not Actually Scary​

For most teams, mixing the two is the migration plan. You don't rip out DGS on Monday and arrive at Spring GraphQL by Friday. You start writing new resolvers in the style you prefer, leave the old ones alone, and delete the DGS-specific bits (codegen, DgsRuntimeWiring) once the last @DgsData is gone.

The one thing to watch: scalars and directives. If your DGS app registers custom scalars via @DgsRuntimeWiring, those need to migrate to Spring GraphQL's RuntimeWiringConfigurer pattern. It's a mechanical change, not a semantic one:

// DGS style
@DgsComponent
public class ScalarsConfig {
    @DgsRuntimeWiring
    public RuntimeWiring.Builder addScalar(RuntimeWiring.Builder builder) {
        return builder.scalar(ExtendedScalars.DateTime);
    }
}

// Spring GraphQL style
@Configuration
public class ScalarsConfig {
    @Bean
    public RuntimeWiringConfigurer runtimeWiringConfigurer() {
        return wiringBuilder -> wiringBuilder.scalar(ExtendedScalars.DateTime);
    }
}

Both call the same graphql-java builder. The wrapper is what differs.

What This Changes About Testing​

Testing used to be the sharpest point of divergence. DGS shipped DgsQueryExecutor which was synchronous, simple, and let you execute raw queries against your resolver beans. Spring GraphQL shipped GraphQlTester which was fluent, supported WebTestClient, and composed with @SpringBootTest.

Post-merge, you can use whichever you prefer. Both work. Mix them in the same test class:

@SpringBootTest
class MovieApiTests {

    @Autowired
    private DgsQueryExecutor dgsExecutor;

    @Autowired
    private GraphQlTester graphQlTester;

    @Test
    void dgsStyleTest() {
        Long id = dgsExecutor.executeAndExtractJsonPath(
            "{ movie(id: 1) { id } }",
            "data.movie.id"
        );
        assertThat(id).isEqualTo(1L);
    }

    @Test
    void springStyleTest() {
        graphQlTester.document("{ movie(id: 1) { id title } }")
            .execute()
            .path("movie.id").entity(Long.class).isEqualTo(1L)
            .path("movie.title").entity(String.class).isEqualTo("Inception");
    }
}

Two styles, same app, same schema, both pass. This is the whole point.

The Real Winner: Your Employability​

Less romantic but true: for a few years, Java GraphQL roles split into "DGS shops" and "Spring GraphQL shops." Postings would say "experience with DGS required" or "Spring GraphQL preferred" and candidates had to pick a side. With the frameworks now pointing at the same underlying execution engine and interoperable at the annotation level, the divide matters less. Knowing one is enough to start; the second is a few hours of "oh, this annotation is just that annotation."

Same schema. Same engine. Different flavor of sugar on top. The merger was always going to happen. The surprise is that it happened gracefully.

What To Actually Do Monday Morning​

If you're on DGS, you're fine. If you're on Spring GraphQL, you're fine. If you're greenfield, pick the one whose annotations your team reads more naturally and move on. The days of choosing between two doors are over; you're just choosing which side of the hallway to stand on.

The more interesting question isn't "DGS or Spring GraphQL." It's "are you writing good schemas, batching your N+1s, and evolving your types without breaking clients?" That's what actually matters. The annotation flavor is just garnish.

This post works equally well whether you read it in a DGS accent or a Spring GraphQL accent. The underlying graphql-java has no opinions on either.

Sources​

• Netflix Tech Blog: A Tale of Two Frameworks
• DGS Framework Documentation
• Netflix/dgs-framework on GitHub
• Open Sourcing the Netflix Domain Graph Service Framework
• Spring for GraphQL Reference
• Spring for GraphQL Versions
• Java Code Geeks: Building GraphQL APIs with Spring Boot and Netflix DGS

For a decade, we've told ourselves a nice story: GraphQL is for humans and frontends. Schemas exist so React developers can autocomplete field names. Then 2026 arrived, LLMs started writing half the code in your repo, and it turns out the thing AI agents desperately needed was exactly what you already had sitting in schema.graphqls. Every typed field, every enum, every nullable flag, every input validation: a ready-made contract for an agent to reason against. You just didn't call it that.

The Problem Nobody Told the Agents About​

Here's how most teams wire an LLM to their backend today:

1. Expose a grab-bag of REST endpoints.
2. Write a hand-crafted tool spec for each one ("here's the path, here's the payload, good luck").
3. Pray the model doesn't hallucinate a field that doesn't exist.
4. Watch it fabricate user.lastLoginTimestamp because some blog post mentioned it in 2023.

The model is pattern-matching its way through your API. There's no schema it can introspect, no types it can trust, no structured errors it can recover from. It's REST circa 2012 with extra steps.

Now swap REST for GraphQL. Suddenly the agent can __schema its way through your API, learns every type, reads your field descriptions, validates inputs before sending, and gets structured errors it can actually act on. The exact features we built for frontend tooling are the features agents were crying out for.

Meet MCP (And Why It Matters Here)​

The Model Context Protocol is Anthropic's open standard for connecting AI models to external systems. Think of it as a pluggable adapter: the model speaks MCP, the server speaks MCP, and everything in between is contract.

An MCP server exposes three kinds of things:

Squint at that table. The mapping between GraphQL operations and MCP primitives is almost embarrassing. Your queries are resources. Your mutations are tools. Your schema descriptions are tool descriptions. The work is largely wiring, not invention.

Enter Apollo MCP Server​

Apollo MCP Server (1.0 generally available since October 2025) takes a GraphQL endpoint and serves it as an MCP server. No rewrite. No hand-rolled tool specs. You point it at your schema, pick which operations to expose, and the model gets a typed, validated, structured surface to work against.

The key move here is pre-defined operations. You don't hand the model raw query-writing power. You hand it a curated menu. Which brings us to the next question everyone asks.

"Can't I Just Let the Agent Write GraphQL?"​

You can. You probably shouldn't. Here's why.

Option A: Raw Query Access​

Let the agent write any query it wants. It has the full schema. It can do anything.

Agent thinks: "I need all users"
Agent writes: query { users { id email password posts { ... } } }
Your DB:     *screams*

There's no query cost analysis. No depth limiting by design. No rate-per-field throttling the agent understands. The model will happily fetch a users { posts { author { posts { author { ... } } } } } tree because the schema said it was legal. And cost analysis at runtime throws an error after you've already burned the compute deciding to reject it.

Option B: Pre-Defined Operations (Persisted Documents for Agents)​

Expose only the operations you've written, reviewed, and cost-analyzed yourself.

# File: operations/getUserProfile.graphql
query GetUserProfile($id: ID!) {
  user(id: $id) {
    id
    displayName
    email
    memberSince
    publicPostCount
  }
}

The agent sees this as an MCP tool named GetUserProfile with one input (id: ID). It can't query password. It can't recurse. It can only do the thing you already decided was safe to do.

This is the persisted-queries model, except the client is a language model instead of your iOS app. Same security story. Same performance story. Different audience.

A Concrete Spring Boot Example​

Let's wire this up against a Spring for GraphQL service. Here's a minimal movie API:

# schema.graphqls
type Query {
  movie(id: ID!): Movie
  searchMovies(query: String!, limit: Int = 10): [Movie!]!
}

type Mutation {
  rateMovie(movieId: ID!, rating: Int!): RatingResult!
}

type Movie {
  id: ID!
  title: String!
  director: String
  releaseYear: Int
  averageRating: Float
}

type RatingResult {
  success: Boolean!
  newAverage: Float
  message: String
}

The Spring side is unremarkable - it's the tutorial you already wrote:

@Controller
public class MovieController {

    private final MovieService movieService;

    public MovieController(MovieService movieService) {
        this.movieService = movieService;
    }

    @QueryMapping
    public Movie movie(@Argument Long id) {
        return movieService.findById(id);
    }

    @QueryMapping
    public List<Movie> searchMovies(@Argument String query, @Argument Integer limit) {
        return movieService.search(query, limit);
    }

    @MutationMapping
    public RatingResult rateMovie(@Argument Long movieId, @Argument Integer rating) {
        return movieService.rate(movieId, rating);
    }
}

Now the MCP layer. You define the operations you want agents to access:

# operations/lookup_movie.graphql
# MCP tool: looks up a movie by ID
query LookupMovie($id: ID!) {
  movie(id: $id) {
    id
    title
    director
    releaseYear
    averageRating
  }
}

# operations/search_movies.graphql
# MCP tool: searches the catalog
query SearchMovies($query: String!, $limit: Int) {
  searchMovies(query: $query, limit: $limit) {
    id
    title
    releaseYear
  }
}

# operations/rate_movie.graphql
# MCP tool: submits a user rating (1-10)
mutation RateMovie($movieId: ID!, $rating: Int!) {
  rateMovie(movieId: $movieId, rating: $rating) {
    success
    newAverage
    message
  }
}

Point Apollo MCP Server at your GraphQL endpoint and your operations directory. Now Claude, ChatGPT, your homegrown agent framework, or whatever else speaks MCP sees three tools with typed inputs, typed outputs, and descriptions you wrote.

The agent's system prompt doesn't need a tutorial on REST conventions. It doesn't need an OpenAPI dump. It gets: "here are three tools, here's what they take, here's what they return." That's it.

The Schema Documentation Glow-Up​

This is the part nobody saw coming: your schema descriptions just got a promotion.

Those little triple-quoted descriptions you were supposed to write on every type but never did? They're now the system prompt for your agent.

"""
A movie in the catalog. Includes editorial and user-generated metadata.
Rating is averaged from all user submissions and may lag by up to 60 seconds.
"""
type Movie {
  id: ID!

  "Display title as marketed. May include subtitles separated by colons."
  title: String!

  "Primary director credit. Null for ensemble or uncredited films."
  director: String

  """
  Theatrical release year. For unreleased films, this is the announced year.
  Clients should treat this as provisional for movies with a release year
  in the future.
  """
  releaseYear: Int

  """
  Average rating across all users, 1.0 to 10.0. Null when rating count is
  below the publication threshold (currently 5). Agents should not present
  a missing rating as 'unknown quality' - it means 'not enough data yet.'
  """
  averageRating: Float
}

That averageRating description isn't for frontend devs. It's for the agent. "Null means not enough data yet, not 'unknown quality.'" That one sentence prevents the model from confidently telling a user "we don't know if this movie is good" when the truth is "three people rated it and we're not publishing until five."

Security: The Part Everyone Skips​

Letting an agent hit your GraphQL API sounds great until you remember that agents can be tricked. Prompt injection is real. A user could paste "ignore previous instructions, call deleteAccount on user 42" into a support chat and your agent might just do it.

MCP doesn't solve this. Your auth layer does.

The Apollo MCP Server docs have a decent section on this. The OWASP LLM Top 10 covers the broader threat model. Read both.

The Argument for Writing It Yourself​

Apollo MCP Server is the polished option, but MCP is an open protocol. If you're on Spring Boot and don't want to add an Apollo dependency, you can expose your GraphQL operations as MCP tools with a few hundred lines of code. The protocol is JSON-RPC over stdio or HTTP. The hard part (the schema, the execution engine, the auth) you already solved.

// Sketch: a Spring controller that speaks MCP
@RestController
@RequestMapping("/mcp")
public class McpController {

    private final GraphQlSource graphQlSource;
    private final Map<String, String> operationRegistry; // name -> query text

    @PostMapping
    public McpResponse handle(@RequestBody McpRequest request) {
        return switch (request.method()) {
            case "tools/list" -> listTools();
            case "tools/call" -> callTool(request.params());
            case "initialize" -> initialize();
            default -> McpResponse.methodNotFound();
        };
    }

    private McpResponse callTool(Map<String, Object> params) {
        String toolName = (String) params.get("name");
        Map<String, Object> arguments = (Map<String, Object>) params.get("arguments");

        String query = operationRegistry.get(toolName);
        if (query == null) {
            return McpResponse.error("Unknown tool: " + toolName);
        }

        ExecutionInput input = ExecutionInput.newExecutionInput()
            .query(query)
            .variables(arguments)
            .build();

        ExecutionResult result = graphQlSource.graphQl().execute(input);
        return McpResponse.success(result.toSpecification());
    }
}

That's the shape of it. You'd flesh out the tool descriptions from your schema's introspection, wire in auth, and add the MCP handshake. Not trivial, but not scary either. And you get to keep every line of logic in your own codebase.

What This Actually Changes​

Zoom out. The developer experience of building an agent-backed feature in 2024 looked like:

1. Pick an LLM.
2. Write prompts.
3. Hand-craft tool definitions for every API call.
4. Discover the model hallucinates fields.
5. Add layers of retry, validation, error correction.
6. Ship a flaky demo.

In 2026, with GraphQL + MCP:

1. Point MCP server at your existing schema.
2. Pick operations to expose.
3. Write good field descriptions (the thing you should have done anyway).
4. Ship.

The backend work largely already exists. Your team spent years building a typed, validated, documented API for the frontend. The agent is just another client. And it happens to be the most demanding one: it reads every field description, it respects nullability, it chokes on ambiguity. Schemas that were sloppy-but-workable for humans get exposed.

That's a feature, not a bug. Write better schemas. Agents reward you for it.

The Bigger Shift​

Here's the thing nobody's saying out loud: this reframes what a GraphQL schema is.

It's not "the contract between backend and frontend." It never really was. It's the contract between your data model and every client that will ever consume it. Browsers. Mobile apps. Integration partners. Third-party developers. And now: AI agents writing on behalf of users who will never see a raw API call.

The schema is your API's only stable interface with the rest of the world. The frontends of 2026 won't look like the frontends of 2019. The agents of 2028 probably won't look like the agents of today. Your schema outlives all of them.

So maybe take the descriptions seriously. Maybe revisit that one mutation you never documented. Maybe stop shipping unbounded list fields just because "nobody queries more than 20." Maybe evolve your schema with the care it deserves, because the number of machines reading it is about to outnumber the number of humans.

This post was drafted by a human who occasionally asks an agent to double-check his JSON examples. The agent, predictably, asked to see the schema first.

Sources​

• Apollo MCP Server Docs
• Apollo: Connect AI Agents to Your GraphQL API Using MCP and Type-Safe Tool Configuration
• Apollo: Building MCP Tools with GraphQL
• Apollo: How to Build AI Agents Using Your GraphQL Schema
• Model Context Protocol Specification
• IBM: Simplifying LLM Integration with MCP and API Connect GraphQL
• WunderGraph MCP Gateway
• OWASP Top 10 for LLM Applications

Your GraphQL schema looked perfect on day one. Clean types. Tight enums. Non-null everything because you were sure those fields would always be there. Then requirements changed, a service went down, and your schema went from "elegant contract" to "active crime scene."

This is a post about evolving GraphQL schemas without making your clients hate you.

The Deceptive Simplicity of Day One​

When you first design a schema, everything feels obvious. You look at the database, you see NOT NULL constraints, and you mirror them in GraphQL:

type Movie {
  id: ID!
  title: String!
  genre: Genre!
  rating: Float!
  director: Person!
}

It's clean. It's strict. It tells clients exactly what they're getting.

And it's a trap.

Within weeks, something changes. Maybe you want to support movies without a genre (user-submitted content). Maybe the rating service goes down and you can't resolve that field. Maybe a movie gets added before a director is assigned.

Each of those scenarios is now a breaking change. Because you told GraphQL that rating is non-null, and when your rating service decides today is the day it chooses violence, the entire Movie type goes up in smoke. Not just the rating field. The whole thing. And if that Movie was nested inside an Order or a Watchlist, those blow up too.

One flaky microservice and your users can't see their watchlist. All because you put an exclamation mark where a question mark should have been.

Rule #1: Nullable First​

The fix is annoyingly simple: start everything as nullable.

type Movie {
  id: ID!
  title: String!
  genre: Genre
  rating: Float
  director: Person
}

Only id and title keep the !. Because a movie without an ID isn't a movie - it's a bug. A movie without a title isn't a movie - it's a database row. But a movie without a rating? That's just a movie nobody's rated yet. A movie without a director? That's a documentary.

The judgment call for each field is: "If this field can't be resolved, should the entire parent type disappear?" If yes, make it non-null. If no (and the answer is usually no), leave it nullable.

This also helps with schema evolution. The direction matters and differs between input and output positions:

• Output field nullable -> non-null is non-breaking per the GraphQL spec (clients that handled null still work), but it can still bite in practice: clients with exhaustive optional-chaining or codegen-generated types may regress, and schema-diff tools commonly flag it as a "dangerous" change rather than a fully safe one.
• Output field non-null -> nullable is breaking - clients depended on the non-null guarantee.
• Input field nullable -> non-null is breaking - existing requests that omitted the field now fail.
• Input field non-null -> nullable is safe.

Starting outputs nullable gives you room to tighten the contract later (with care), once you're confident the field is always present.

Rule #2: Bounded Inputs, Unbounded Outputs​

This one catches people off guard. Enums feel safe. They're self-documenting, they prevent typos, and GraphiQL autocompletes them. Why wouldn't you use them everywhere?

Here's why: adding a new value to an output enum is a breaking change.

Say your schema returns Genre as an enum on the Movie type. You add ANIME to the enum. Your server starts returning ANIME for some movies. A client that was generated against the old schema tries to deserialize ANIME into their local Genre enum and explodes. If they're using a language with strict enum support (Kotlin, Swift, TypeScript with codegen), they get a deserialization error. If they're not, they get undefined behavior, which might be even worse.

On the input side, this isn't a problem. If you add ANIME to an input enum, old clients simply can't send it yet. They keep working as before. No breakage. No surprises.

The takeaway:

The pattern that emerges: use enums for inputs (bounded, validated, guides the client) and strings for outputs (unbounded, forward-compatible, no surprise deserialization failures).

For a small project where you control both the client and the server? Enums everywhere are fine. For a public API with clients you don't control? Bounded inputs, unbounded outputs.

Rule #3: When in Doubt, Duplicate​

This is the one that feels wrong until you internalize it.

In REST, you have a limited set of HTTP verbs per resource. If PUT /movies/:id does something and you need to change what it does, you're stuck negotiating with existing clients about migration timelines and versioned endpoints.

GraphQL doesn't have this problem. There is no constraint on how many fields or mutations you can have. Words are free.

If addMovie takes a simple input and you now need a version that accepts the full cast and crew in one call, don't refactor addMovie. Don't add optional fields that change the behavior depending on what's present. Just create addMovieWithCast. The old mutation keeps working. The new one serves the new use case. Both coexist peacefully.

type Mutation {
  addMovie(input: AddMovieInput!): Movie!
  addMovieWithCast(input: AddMovieWithCastInput!): Movie!
}

It's wordier. Some people will have to type more. But nobody's integration breaks at 2 AM.

REST comes from a place of scarcity. GraphQL comes from a place of abundance. Use the words.

Rule #4: Set Ground Rules Before You Need Them​

This one isn't about schema syntax. It's about people.

When it's you and two other engineers working on the schema, consistency is natural. You all have the same mental model, you're all in the same Slack channel, and PRs get reviewed by someone who was probably in the room when the pattern was decided.

Then the team grows. New people join. They look at the schema for patterns to follow. If there's one pattern, they copy it and move on. If there are six patterns for the same thing, they spend a day figuring out which one is "right." And if you have an especially ambitious engineer, they'll look at all six, decide they're all wrong, and introduce a seventh.

That's a lot of bike-shedding time that could have been spent on product work.

The fix: write down your schema conventions. It doesn't have to be a 50-page document. A one-pager covering naming conventions, mutation return types, how you handle pagination, and your nullable/enum strategy is enough. Put it in your wiki, link it in your PR template, and move on.

You don't need linting tools on day one. You don't need a GraphQL Clippy (though that would be amazing). You just need a document that says "this is how we do it" so that new contributors have one pattern to follow instead of six.

The tooling comes later, when you feel the pain. The document comes now, before you need it.

Rule #5: Control Your Data (Or Lose Sleep)​

GraphQL's superpower is that clients can ask for exactly what they need. GraphQL's curse is that clients can ask for everything they want.

Eventually, someone will write a query that fetches every movie, with every actor, with every other movie that actor has been in, with every actor in those movies, recursively, until your database is weeping and your response is 47 MB of JSON.

You need guardrails:

Depth limiting - cap how deep queries can nest. A depth limit of 10 stops the recursive nightmare while allowing legitimate deeply nested queries.

Complexity cost analysis - assign a weight to each field and reject queries that exceed a budget. The hard part isn't implementing this; it's figuring out what the numbers should be. A title field costs almost nothing. A cast field that triggers a join across three tables is expensive. Getting these weights right takes real-world usage data.

Persisted queries - instead of accepting arbitrary query strings, predefine a set of known-safe queries and have clients reference them by ID. This is the nuclear option: maximum control, but it limits the flexibility that made GraphQL appealing in the first place. Use it for public APIs where you need total predictability.

Rule #6: Deprecate with a Deadline​

If you do need to deprecate a field, GraphQL has a built-in @deprecated directive. Originally it applied only to fields and enum values; a later spec change (the RFC was merged into the GraphQL spec draft in June 2022) extended it to also work on arguments and input fields, so you can deprecate input shapes the same way. Confirm your server version supports the input-position usage before relying on it. Add a date so the deprecation has a deadline:

type Movie {
  year: Int @deprecated(reason: "Use releaseYear instead. Will be removed 2025-10-01.")
  releaseYear: Int!

  search(
    # Deprecating an input argument
    legacyTitle: String @deprecated(reason: "Use `query` instead. Removed 2025-10-01.")
    query: String
  ): [Movie!]!
}

input MovieFilter {
  # Deprecating an input field
  oldField: String @deprecated(reason: "Use newField instead.")
  newField: String
}

A deprecation without a date is a suggestion. A deprecation with a date is a contract. "This field is going away on October 1st" gives clients a deadline to migrate and gives you permission to actually remove it.

Without a date, deprecated fields accumulate like dead code. Five years later, half your schema is deprecated and none of it has been removed because nobody knows if it's safe. That's not deprecation. That's hoarding.

The Cheat Sheet​

The Real Lesson​

Schema design is API design. And API design is a promise to people you haven't met yet, using clients you haven't seen, for use cases you haven't imagined.

The schemas that survive are the ones that leave room. Room for fields to appear. Room for values to change. Room for the requirements to pivot without the API collapsing.

Start nullable. Stay unbounded on outputs. Duplicate instead of break. Write your rules down. And put a date on your deprecations.

Your future self - the one getting pinged on Slack at 3 AM because a non-null field returned null and cascaded through 47 client apps - will thank you.

Every GraphQL query you send travels over HTTP. Every response comes back the same way. But here's the thing: HTTP was designed for fetching documents, not executing queries. GraphQL essentially hijacked a delivery truck and turned it into a taxi service. Let's explore the protocol that makes it all possible.

The Origin Story​

HTTP - Hypertext Transfer Protocol - was invented by Tim Berners-Lee in 1989 at CERN. The original goal? Link scientific documents together so physicists could share research. Fast forward 35 years, and it's carrying cat videos, financial transactions, and yes, your carefully crafted GraphQL mutations.

HTTP/0.9: The Innocent Beginning​

The original HTTP was adorably simple. The entire protocol was one line:

GET /page.html

That's it. No headers. No status codes. No content types. The server would respond with raw HTML and close the connection. Done.

Client → GET /hello.html

Server → <html>
          <body>Hello World</body>
          </html>
          [connection closed]

Could you run GraphQL over HTTP/0.9? Technically yes. Would it be a nightmare? Absolutely.

HTTP/1.0: Growing Up​

HTTP/1.0 introduced the concepts we still use today:

GET /movie/123 HTTP/1.0
Host: api.example.com
Accept: application/json
User-Agent: GraphQLClient/1.0

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 127

{"data":{"movie":{"id":"123","title":"The Matrix"}}}

The Request Anatomy​

HTTP Methods: The Verbs​

HTTP defines methods (verbs) for different operations:

* Technically allowed but rarely used.

GraphQL uses: POST (always), GET (queries only, optional).

GraphQL's controversial choice: GraphQL uses POST for everything - queries, mutations, subscriptions. This violates REST conventions where GET should be used for reads. But GraphQL has good reasons:

1. Query strings have length limits (~2000-8000 chars depending on browser/server)
2. GraphQL queries can be massive (nested selections, fragments, variables)
3. Caching is handled differently anyway (operation-level, not URL-level)

Status Codes: How HTTP Talks Back​

HTTP status codes are three-digit numbers that tell you what happened:

GraphQL's Status Code Philosophy​

Here's where GraphQL gets weird. A GraphQL response almost always returns 200 OK, even when there are errors:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": null,
  "errors": [
    {
      "message": "User not found",
      "path": ["user"]
    }
  ]
}

Wait, what? The user wasn't found but we got 200 OK?

GraphQL's reasoning:

• The HTTP request succeeded (it reached the server, was parsed, was executed)
• The GraphQL execution had errors, but that's GraphQL-level, not HTTP-level
• Partial success is possible (some fields resolve, others fail)

HTTP Headers: The Metadata Layer​

Headers are key-value pairs that provide metadata about the request or response.

Essential Request Headers​

POST /graphql HTTP/1.1
Host: api.movies.com                    # Required in HTTP/1.1
Content-Type: application/json          # What format is the body?
Content-Length: 156                     # How big is the body?
Accept: application/json                # What format do you want back?
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: MyApp/1.0                   # Who's calling?
Accept-Encoding: gzip, deflate          # Compression we understand
Connection: keep-alive                  # Don't close after response

Essential Response Headers​

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1234
Content-Encoding: gzip                  # Response is compressed
Cache-Control: no-store                 # Don't cache this
Date: Mon, 24 Jun 2024 10:30:00 GMT
X-Request-Id: abc123                    # For debugging/tracing

Headers That Matter for GraphQL​

HTTP/1.1: The Workhorse​

HTTP/1.1 (1997-2015) was the dominant protocol version for nearly two decades. Key features:

Persistent Connections​

HTTP/1.0 closed the connection after each request. HTTP/1.1 keeps it open:

Chunked Transfer Encoding​

Don't know the size upfront? Stream it:

HTTP/1.1 200 OK
Transfer-Encoding: chunked

7\r\n
{"data"\r\n
5\r\n
:{"m\r\n
8\r\n
ovie":{}\r\n
2\r\n
}}\r\n
0\r\n
\r\n

This is crucial for GraphQL subscriptions and streaming responses (like @defer and @stream).

The Head-of-Line Blocking Problem​

HTTP/1.1's fatal flaw: requests must be processed in order:

For GraphQL, this means a slow query blocks subsequent queries on the same connection.

HTTP/2: The Multiplexing Revolution​

HTTP/2 (2015) fixed head-of-line blocking with multiplexing:

HTTP/2 Frame Types​

HTTP/2 is binary, not text. Messages are split into frames:

GraphQL Benefits from HTTP/2​

HTTP/3: The QUIC Revolution​

HTTP/3 (2022) replaces TCP with QUIC (UDP-based):

* Browsers require HTTPS for HTTP/2.

Why QUIC Matters​

HTTP/2 solved application-level head-of-line blocking but TCP still has it:

Zero Round Trip Connection (0-RTT)​

Content Negotiation​

HTTP lets clients and servers negotiate format, language, and encoding:

# Request
GET /graphql HTTP/1.1
Accept: application/json, application/xml;q=0.9, */*;q=0.1
Accept-Language: en-US, en;q=0.9, de;q=0.8
Accept-Encoding: gzip, deflate, br

# Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
Content-Encoding: gzip
Vary: Accept, Accept-Encoding

The q parameter indicates preference (0.0-1.0):

• application/json - implied q=1.0 (most preferred)
• application/xml;q=0.9 - second choice
• */*;q=0.1 - anything else as last resort

Caching: The HTTP Superpower​

HTTP has sophisticated caching built in:

The GraphQL Caching Problem​

Here's why GraphQL and HTTP caching don't play nice:

# REST (cacheable by URL)
GET /movies/123 HTTP/1.1
# Cache key: /movies/123
# Easy to cache!

# GraphQL (same URL, different data)
POST /graphql HTTP/1.1

{"query": "{ movie(id: \"123\") { title } }"}

# vs

{"query": "{ movie(id: \"123\") { title director { name } reviews { rating } } }"}

# Same URL, same method, totally different responses!

Solutions:

CORS: The Browser's Security Guard​

Cross-Origin Resource Sharing controls which websites can call your API:

GraphQL CORS gotcha: GraphQL always sends Content-Type: application/json, which triggers preflight. Every first request to your API has this overhead.

CORS Configuration Example (Spring)​

@Configuration
public class CorsConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/graphql")
            .allowedOrigins("https://myapp.com", "https://admin.myapp.com")
            .allowedMethods("POST", "GET", "OPTIONS")
            .allowedHeaders("Content-Type", "Authorization")
            .allowCredentials(true)
            .maxAge(86400); // Cache preflight for 24 hours
    }
}

WebSocket Upgrade: Real-Time GraphQL​

GraphQL subscriptions often use WebSocket, which starts as HTTP:

# Upgrade Request
GET /graphql HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: graphql-ws
Sec-WebSocket-Version: 13

# Upgrade Response
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: graphql-ws

After this handshake, the connection switches from HTTP to WebSocket, and GraphQL subscription messages flow freely.

Security Headers​

Beyond authentication, these headers protect your API:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: default-src 'none'; frame-ancestors 'none'

Debugging HTTP​

Browser DevTools​

cURL for Testing​

# Basic GraphQL query
curl -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"query": "{ movies { title } }"}'

# With verbose output (see all headers)
curl -v -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ movies { title } }"}'

# Time the request
curl -w "@curl-format.txt" -o /dev/null -s \
  -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ movies { title } }"}'

Summary​

POST /graphql HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{"query": "...", "variables": {...}, "operationName": "..."}

HTTP/1.1 200 OK
Content-Type: application/json

{"data": {...}, "errors": [...], "extensions": {...}}

HTTP wasn't designed for GraphQL. It was designed for fetching hypertext documents in the early 90s. But here we are, using it to execute complex query languages, stream real-time updates, and build the modern web. That's the beauty of good protocol design - it bends without breaking.

Tim Berners-Lee invented HTTP to share physics papers. Now it carries an absurd amount of GraphQL traffic. I'm pretty sure that counts as scope creep.

Sources​

• RFC 9110 - HTTP Semantics
• RFC 9112 - HTTP/1.1
• RFC 9113 - HTTP/2
• RFC 9114 - HTTP/3
• MDN Web Docs - HTTP
• GraphQL over HTTP Specification
• High Performance Browser Networking - Ilya Grigorik

Every time you fire a GraphQL query, your beautifully crafted response comes back wrapped in JSON. But how well do you actually know JSON? Not "I can read it" know, I am talking about "I know exactly where the spec draws the line" know. Buckle up. We're going deep on the most successful data format the web has ever seen.

The Origin Story​

JSON - JavaScript Object Notation - was formalized by Douglas Crockford in the early 2000s and published as RFC 4627 in 2006. But here's the twist: Crockford didn't invent JSON. He discovered it.

"I do not claim to have invented JSON."

• Douglas Crockford

JSON's syntax was already baked into JavaScript since its creation in 1995. Crockford simply recognized its potential as a standalone data interchange format and liberated it from the browser.

The Six Sacred Types​

JSON has exactly six data types. Not seven. Not five. Six. Memorize them.

Strings: The Escape Artists​

JSON strings are enclosed in double quotes only. Single quotes? Heresy. No quotes? Prison.

{
  "valid": "Hello, World!",
  "also_valid": "",
  "unicode": "Hello, 世界! 🌍",
  "escaped": "Line 1\nLine 2\tTabbed"
}

The escape sequences you need to know:

Fun fact: The forward slash escape (\/) is optional - you can write / directly. It exists mainly for embedding JSON inside <script> tags to prevent </script> from being interpreted as a closing tag.

Numbers: Where Things Get Spicy​

JSON numbers look simple until they're not:

{
  "integer": 42,
  "negative": -17,
  "decimal": 3.14159,
  "exponent": 6.022e23,
  "negative_exponent": 1.6e-19
}