Add support for newer incremental delivery format by jerelmiller · Pull Request #8148 · apollographql/apollo-server

jerelmiller · 2025-09-25T01:21:32Z

Adds support for the [email protected] @defer and @stream incremental delivery protocol.

When [email protected] is installed, clients must send the Accept header with a value of multipart/mixed; incrementalSpec=v0.2 to specify the new format. If the Accept header is not compatible with the installed version of graphql (such as sending deferSpec=20220824 when ``17.0.0-alpha.9` is installed), an error is returned to the client.

apollo-librarian · 2025-09-25T01:21:40Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* (developer-tools)/apollo-server/(latest)/workflow/requests.md

Build ID: dc85da527b6ca91985ac90df
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/dc85da527b6ca91985ac90df

codesandbox-ci · 2025-09-25T01:22:18Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

packages/server/src/externalTypes/incrementalDeliveryPolyfillAlpha9.ts

glasser · 2025-10-01T22:38:56Z

.changeset/fruity-ways-tell.md

+'@apollo/server': minor
+---
+
+Apollo Server now supports the modern incremental delivery protocol (`@defer` and `@stream`) that ships with `[email protected]`. To use the modern protocol, clients must send the `Accept` header with a value of `multipart/mixed; incrementalDeliverySpec=3283f8a`.


I wonder if "modern" is an overly optimistic term to use throughout this PR. If we come up with a third protocol later, it won't age well. Would "current" work better than "modern"?

This is why I hate naming 😂. I just picked something to differentiate from it and the legacy version. I didn't really find a good name for the "now" version, but I'd be ok with "current" 🙂

Updated in 3c0a88e

I think the term is also used in errors?

Oops, you're right! Updated in 5d15554

Co-authored-by: David Glasser <[email protected]>

docs/source/workflow/requests.md

glasser

I think you've addressed all my concerns from last time.

I'm not really sure what the v0.1 refers to but it's as good as anything else. Have you tested what happens when both deferSpec and incrementalDeliverySpec are sent? Would be good to make that well-defined, but not necessary.

This isn't a regression, but it might be nice to be explicit somewhere that --legacy-peer-deps is required for installing the alpha and transform.

jerelmiller · 2025-10-14T18:52:37Z

🙌

I'm not really sure what the v0.1 refers to but it's as good as anything else.

We're going to document the spec as it exists today in specs.apollo.dev. @calvincestari has a PR up right now to add this: apollographql/specs#67

That v0.1 refers to the version in that PR. We figure this is a good way to reference the spec as implemented in that version. If new ones come along, we can add v0.2, 0.3, etc for as long as we need until the spec is stable. But we plan to have those versions documented to capture the spec as it exists at the time we add support for the version.

Have you tested what happens when both deferSpec and incrementalDeliverySpec are sent?

Actually no! I'll try this out. I believe it will return the newer version of the spec (since it uses Negotiator and prefers that version), but wouldn't hurt to add an explicit test.

This isn't a regression, but it might be nice to be explicit somewhere that --legacy-peer-deps is required for installing the alpha and transform.

Good call. I'll see if I can update the docs page and include that.

Updates the header based on changes in apollographql/apollo-server#8148

…al-spec

@jerelmiller

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. ⚠️

⚠️

⚠️ `main` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `main`. ⚠️

⚠️

⚠️ # Releases ## @apollo/[email protected] ### Minor Changes - [#8148](#8148) [`80a1a1a`](80a1a1a) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Apollo Server now supports the incremental delivery protocol (`@defer` and `@stream`) that ships with `[email protected]`. To use the current protocol, clients must send the `Accept` header with a value of `multipart/mixed; incrementalSpec=v0.2`. Upgrading to 5.1 will depend on what version of `graphql` you have installed and whether you already support the incremental delivery protocol. ## I use `graphql@16` without incremental delivery Continue using `graphql` v16 with no additional changes. Incremental delivery won't be available. ## I use `graphql@16` but would like to add support for incremental delivery Install `[email protected]` and follow the ["Incremental delivery" guide](https://www.apollographql.com/docs/apollo-server/workflow/requests#incremental-delivery-experimental) to add the `@defer` and `@stream` directives to your schema. Clients should send the `Accept` header with a value of `multipart/mixed; incrementalSpec=v0.2` to get multipart responses. ## I use `[email protected]` and use incremental delivery You must upgrade to `[email protected]` to continue using incremental delivery. If you'd like to continue providing support for the legacy incremental protocol, install the [`@yaacovcr/transform`](https://github.com/yaacovCR/transform) package. Apollo Server will attempt to load this module when the client specifies an `Accept` header with a value of `multipart/mixed; deferSpec=20220824`. If this package is not installed, an error is returned by the server. Because Apollo Server now supports multiple versions of the incremental delivery types, the existing incremental delivery types have been renamed with an `Alpha2` suffix. If you import these types in your code, you will need to add the `Alpha2` suffix. ```diff import type { - GraphQLExperimentalFormattedInitialIncrementalExecutionResult, + GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha2, - GraphQLExperimentalFormattedSubsequentIncrementalExecutionResult, + GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha2, - GraphQLExperimentalFormattedIncrementalResult, + GraphQLExperimentalFormattedIncrementalResultAlpha2, - GraphQLExperimentalFormattedIncrementalDeferResult, + GraphQLExperimentalFormattedIncrementalDeferResultAlpha2, - GraphQLExperimentalFormattedIncrementalStreamResult, + GraphQLExperimentalFormattedIncrementalStreamResultAlpha2, } from '@apollo/server'; ``` Incremental delivery types for the `[email protected]` version are now available using the `Alpha9` suffix: ```ts import type { GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha9, GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha9, GraphQLExperimentalFormattedIncrementalResultAlpha9, GraphQLExperimentalFormattedIncrementalDeferResultAlpha9, GraphQLExperimentalFormattedIncrementalStreamResultAlpha9, GraphQLExperimentalFormattedCompletedResultAlpha9, GraphQLExperimentalPendingResultAlpha9, } from '@apollo/server'; ``` ## @apollo/[email protected] ### Patch Changes - Updated dependencies \[[`80a1a1a`](80a1a1a)]: - @apollo/[email protected] ## @apollo/[email protected] ### Patch Changes - Updated dependencies \[[`80a1a1a`](80a1a1a)]: - @apollo/[email protected] --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jerel Miller <[email protected]>

@jerelmiller

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @apollo/[email protected] ### Minor Changes - [#8148](#8148) [`80a1a1a`](80a1a1a) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Apollo Server now supports the incremental delivery protocol (`@defer` and `@stream`) that ships with `[email protected]`. To use the current protocol, clients must send the `Accept` header with a value of `multipart/mixed; incrementalSpec=v0.2`. Upgrading to 5.1 will depend on what version of `graphql` you have installed and whether you already support the incremental delivery protocol. ## I use `graphql@16` without incremental delivery Continue using `graphql` v16 with no additional changes. Incremental delivery won't be available. ## I use `graphql@16` but would like to add support for incremental delivery Install `[email protected]` and follow the ["Incremental delivery" guide](https://www.apollographql.com/docs/apollo-server/workflow/requests#incremental-delivery-experimental) to add the `@defer` and `@stream` directives to your schema. Clients should send the `Accept` header with a value of `multipart/mixed; incrementalSpec=v0.2` to get multipart responses. ## I use `[email protected]` and use incremental delivery You must upgrade to `[email protected]` to continue using incremental delivery. If you'd like to continue providing support for the legacy incremental protocol, install the [`@yaacovcr/transform`](https://github.com/yaacovCR/transform) package. Apollo Server will attempt to load this module when the client specifies an `Accept` header with a value of `multipart/mixed; deferSpec=20220824`. If this package is not installed, an error is returned by the server. Because Apollo Server now supports multiple versions of the incremental delivery types, the existing incremental delivery types have been renamed with an `Alpha2` suffix. If you import these types in your code, you will need to add the `Alpha2` suffix. ```diff import type { - GraphQLExperimentalFormattedInitialIncrementalExecutionResult, + GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha2, - GraphQLExperimentalFormattedSubsequentIncrementalExecutionResult, + GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha2, - GraphQLExperimentalFormattedIncrementalResult, + GraphQLExperimentalFormattedIncrementalResultAlpha2, - GraphQLExperimentalFormattedIncrementalDeferResult, + GraphQLExperimentalFormattedIncrementalDeferResultAlpha2, - GraphQLExperimentalFormattedIncrementalStreamResult, + GraphQLExperimentalFormattedIncrementalStreamResultAlpha2, } from '@apollo/server'; ``` Incremental delivery types for the `[email protected]` version are now available using the `Alpha9` suffix: ```ts import type { GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha9, GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha9, GraphQLExperimentalFormattedIncrementalResultAlpha9, GraphQLExperimentalFormattedIncrementalDeferResultAlpha9, GraphQLExperimentalFormattedIncrementalStreamResultAlpha9, GraphQLExperimentalFormattedCompletedResultAlpha9, GraphQLExperimentalPendingResultAlpha9, } from '@apollo/server'; ``` ## @apollo/[email protected] ### Patch Changes - Updated dependencies \[[`80a1a1a`](80a1a1a)]: - @apollo/[email protected] --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jerel Miller <[email protected]>

Updates the header based on changes in apollographql/apollo-server#8148

jerelmiller added 28 commits September 23, 2025 18:07

DeMorgan's Law

9274bb7

Compare against no defer spec

922da17

Add new multipart mixed header

0bb58a0

Update request error message to suggest new format

9b63f24

Add Alpha2 suffix to existing incremental types

7a8292c

Add Alpha2 suffix to polyfill file

852a6a6

Add polyfill types for alpha9

8ac5c71

Export alpha9 types

96112c0

Remove ordering of incremental fields

56245aa

Add type for GraphQLResponseBody with alpha 9 format

92fa99b

Update writeMultipartBody signature

fbfa0df

Update payload type for willSendSubsequentPayload

c7abd87

Load from alpha 9

4d3beb0

Add alpha2 suffix to existing execute types and add alpha9 types

d6e19f6

Update ApolloServer types

ddddd79

Update constructor types

bb827ce

Ensure executeIncrementally returns alpha9 types

0da6d92

Handle formatting alpha9 errors

d8fa3ec

Throw if version mismatch from header

bd8d0c3

Simplify check

1916a46

Rename media types

5ec9b5e

Change value of alpha9 spec version

5aa7578

Change output header depending on graphql version

48e2572

Swap order of conditional

c2403d5

Enable incremental delivery tests for alpha9

b7ce974

Wrap existing tests in check for alpha2

5c7bed1

Add back field ordering

7df7889

Enable incremental delivery tests for alpha9

758f50f

glasser reviewed Oct 1, 2025

View reviewed changes

jerelmiller and others added 7 commits October 1, 2025 16:41

Fix typo

28e9d9c

Co-authored-by: David Glasser <[email protected]>

Grammar

b32394a

Remove use of "modern" in changeset

3c0a88e

Revert changes to peer deps

bd5cd63

Don't export unneeded types

96af552

Update error messages

5d15554

Update incrementalDeliverySpec header value

79fb340

jerelmiller commented Oct 14, 2025

View reviewed changes

docs/source/workflow/requests.md Outdated Show resolved Hide resolved

Fix typo

77b57de

jerelmiller requested review from BoD, glasser, martinbonnin and phryneas October 14, 2025 18:22

jerelmiller mentioned this pull request Oct 14, 2025

Update accept header used with GraphQL17Alpha9Handler apollographql/apollo-client#12973

Merged

glasser approved these changes Oct 14, 2025

View reviewed changes

calvincestari mentioned this pull request Oct 16, 2025

Adding first draft of incremental delivery spec artifact apollographql/specs#67

Merged

Update header value to final version

8b4bea5

jerelmiller added a commit to apollographql/apollo-client that referenced this pull request Oct 21, 2025

Update accept header used with GraphQL17Alpha9Handler (#12973)

072da24

Updates the header based on changes in apollographql/apollo-server#8148

Merge remote-tracking branch 'origin/main' into jerel/newer-increment…

6871901

…al-spec

jerelmiller enabled auto-merge (squash) October 21, 2025 16:30

jerelmiller merged commit 80a1a1a into main Oct 21, 2025
15 of 17 checks passed

jerelmiller deleted the jerel/newer-incremental-spec branch October 21, 2025 16:42

github-actions bot mentioned this pull request Oct 21, 2025

Version Packages (rc) #8153

Merged

github-actions bot mentioned this pull request Oct 28, 2025

Version Packages #8155

Merged

jerelmiller added a commit to apollographql/apollo-client that referenced this pull request Nov 17, 2025

Update accept header used with GraphQL17Alpha9Handler (#12973)

5776ea0

Updates the header based on changes in apollographql/apollo-server#8148

github-actions bot locked as resolved and limited conversation to collaborators Nov 22, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for newer incremental delivery format#8148

Add support for newer incremental delivery format#8148
jerelmiller merged 94 commits intomainfrom
jerel/newer-incremental-spec

jerelmiller commented Sep 25, 2025 •

edited

Loading

Uh oh!

apollo-librarian bot commented Sep 25, 2025 •

edited

Loading

Uh oh!

codesandbox-ci bot commented Sep 25, 2025 •

edited

Loading

Uh oh!

Uh oh!

glasser Oct 1, 2025

Uh oh!

jerelmiller Oct 1, 2025

Uh oh!

jerelmiller Oct 1, 2025

Uh oh!

glasser Oct 1, 2025

Uh oh!

jerelmiller Oct 1, 2025

Uh oh!

Uh oh!

glasser left a comment

Uh oh!

jerelmiller commented Oct 14, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

jerelmiller commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apollo-librarian bot commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

codesandbox-ci bot commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

glasser Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

glasser Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

glasser left a comment

Choose a reason for hiding this comment

Uh oh!

jerelmiller commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jerelmiller commented Sep 25, 2025 •

edited

Loading

apollo-librarian bot commented Sep 25, 2025 •

edited

Loading

codesandbox-ci bot commented Sep 25, 2025 •

edited

Loading

jerelmiller commented Oct 14, 2025 •

edited

Loading