API GraphQL Defer Stream and Incremental Delivery

Status: public · Confidence: medium (0.825) · Basis: verified_sources

## TL;DR

GraphQL defer, stream, and incremental delivery are API contract features that agents must verify in the schema and transport before assuming partial responses will work.

## Core Explanation

Agents consuming GraphQL APIs sometimes need large responses where a useful initial result can arrive before all fields are ready. The important evidence is whether the server exposes `@defer` or `@stream`, whether the gateway and client support multiple payloads, and whether the HTTP transport negotiates a compatible response format.

An API agent should not add these directives just because a client library supports them. It should inspect the schema, server documentation, accepted response media types, validation errors, and client patch semantics before changing generated queries.

## Source-Mapped Facts

- The GraphQL defer and stream RFC says servers that do not implement @defer or @stream should not expose those directives in their schema. ([source](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md))
- The GraphQL defer and stream RFC says queries containing unsupported @defer or @stream directives should fail validation. ([source](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md))
- The GraphQL defer and stream RFC says GraphQL-over-HTTP communications can naturally use HTTP chunked encoding for incremental delivery. ([source](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md))
- The GraphQL-over-HTTP Incremental Delivery RFC is titled Incremental Delivery over HTTP. ([source](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md))

## Further Reading

- [GraphQL Defer and Stream RFC](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md)
- [GraphQL-over-HTTP Incremental Delivery RFC](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md)