5.0.0

Apollo Kotlin 5 is a major release focused on:

• GraphQL golden path: incremental delivery (@defer/@stream), fragment arguments, service capabilities, onError, nullability, field extensions, @oneOf, schema coordinates, ...
• Modernized infrastructure: KGP 2.3.10, Gradle 9, AGP 9, classloader isolation, isolated projects support.

In addition, Apollo Kotlin 5 stabilizes the new WebSocket engine, adds new KMP targets, a new HTTP cache strategy on top of OkHttp, new compiler plugin APIs, and more.

Previous DeprecationLevel.WARNING symbols are now DeprecationLevel.ERROR.
Previous DeprecationLevel.ERROR symbols are removed.

Apollo Kotlin 5 is an incremental release. Most of the APIs are compatible with Apollo Kotlin 4. The main breaking changes are in experimental Data Builders and Apollo Compiler Plugins.

For an upgrade walkthrough, see the v5 migration guide.

🚀 GraphQL golden path

Apollo Kotlin 5 implements the latest version of the GraphQL specification draft as well as support for many experimental RFCs.

Those RFCs solve long-standing pain points in GraphQL, such as semantic nullability or fragment arguments.

• Add incremental/v0.2 format for @defer and @stream (#6331).
• Add fragment arguments (#6882).
• Add support for onError (#6860).
• Add support for service capabilities (#6858).
• Add field extensions (#6856, #6867).
• Add schema coordinates (#6560).
• Add @ignore support (#6900).
• Add support descriptions on variable definitions (#6699).
• Add support for directives on directive definitions (#6803).
• Speed up field merging validation (#6875).
• Validate @oneOf input objects when they create cycles (#6894).

🧰 Modernized infrastructure

The Gradle plugin now uses Gratatouille classloader isolation, instead of GR8 relocation previously (#6524). This makes the plugin more robust and easier to debug.

Apollo Kotlin 5 uses KGP 2.3, with 2.1 compatibility for JVM and Android consumers. Native and JS consumers must compile with KGP 2.3+.

• Switch the Gradle plugin to Gratatouille (#6524).
• Simplify task wiring and propagate task dependencies in multi-module setups (#6562, #6879).
• Avoid eager configuration of Gradle objects (#6820).
• Add linuxX64 (#6493), linuxArm64 (#6929) and watchosDeviceArm64 (#6791) targets.
• Bump to 2.3.10 (#6873). Native/JS/Wasm consumers must compile with Kotlin 2.3.
• Update to Gradle 9 (#6548, #6652, #6769, #6862, #6887).
• Bump Ktor to 3.1.2 (#6465).
• AGP9 support, including com.android.kotlin.multiplatform.library (#6703, #6707, #6736).
• Add a default Accept header to introspection queries (#6616).

🚗 Runtime

Apollo Kotlin 5 stabilizes the new WebSocket API, making it easier to manage the lifecycle of the WebSocket and retry subscriptions.

• Promote experimental WebSockets to stable; the previous implementation (under com.apollographql.apollo.ws) is deprecated (#6774).
• Add RetryStrategy (#6764).
• Add ApolloRequest.Builder.url(String) (#6758).
• Add ApolloCall.extensions() (#6834).
• Add ApolloCall.ignoreUnknownKeys and ApolloClient.Builder.ignoreUnknownKeys (#6473).
• Restore JsonReader state if a field throws in-flight (#6775).
• Make Optional.Absent a data object (#6686); use if/else to avoid Int boxing (#6688).

🗄️ Normalized cache

The normalized cache artifacts are also deprecated and moved to a separate repository apollo-kotlin-normalized-cache (#6888).

This new cache supports:

• TTL
• Garbage collection
• Pagination
• Partial results

Note that the SQLite storage format is not backward-compatible. See the dedicated migration guide for more details.

🌐 HTTP cache

The legacy apollo-http-cache artifact is deprecated.

Instead, Apollo Kotlin now uses OkHttp's cacheUrlOverride() and supports POST caching via enablePostCaching (#6739).

See the migration guide for more details.

🛠️ Compiler & AST

• Add schema-transform API (#6450).
• Allow registering multiple compiler plugins; introduce Service.pluginsArguments (#6523, #6622).
• Add Service.issueSeverity() to control the severity of compiler issues per type (#6731).
• Introduce Service.generateApolloEnums to generate enums as a sealed hierarchy with a __Known interface (#6611).
• Allow generating Data Builders outside the main source set (#6485).
• Add generateApolloProjectIdeModel task (#6666).
• Add a specific issue type for fragment cycles (#6759).
• Move validation tests to apollo-ast (#6868).
• Reorganize parser, introspection, and merger tests (#6857).
• Warn on unused fragments (#6601).
• Pretty-print the operation manifest (#6720).
• Allow empty deprecation messages (#6729, #6779).
• Add key fields of possible types of interfaces and fragments (#6515).
• Add key fields to selections even when they're already selected with an alias (#6503).
• Transform GraphQL documents before running validation (#6511).
• Call DocumentTransform.transform after processing (#6510).
• Rename @link Purpose and Import definitions (#6838).
• Escape names in equals(), hashCode(), copy(), and toString() (#6843).
• Escape /* and */ in KDocs (#6805).
• Ignore scalars/enums in checkCapitalizedFields (#6502).
• Fix IndexOutOfBoundsException in keyFields validation (#6748).
• Do not check already-checked fragments in checkCapitalizedFields (#6718).

5.0.0-rc.1

This version is the same as 5.0.0-rc.0 with a fix for a performance regression in the compiler (#6938). Many thanks @apramana for diving into this.

5.0.0-rc.0

First release candidate of Apollo Kotlin 5.

• [NEW] Add linuxArm64 target (#6929)
• [NEW] Add linux WebSockets support (#6929)
• [FIX] Always strip @catchByDefault in executable documents (#6932)
• [FIX] Cache: merge data in the presence of include directives (#6922)

v5.0.0-alpha.7

Compatibility release for Kotlin 2.4.0-Beta1

• [NEW] Pass parent and parentType to FakeResolver (#6913)
• [FIX] Compatibility with Kotlin 2.4-Beta1: Remove legacy JS target check (#6908)

Full Changelog: v5.0.0-alpha.6...v5.0.0-alpha.7

v4.4.3

Compatibility release for Kotlin 2.4.0-Beta1. This release contains only a single change:

• [FIX] Compatibility with Kotlin 2.4-Beta1: Remove legacy JS target check (#6910)

v5.0.0-alpha.6

This version is probably one of the last alpha before going -rc.

• [NEW] Add support for @ignore (#6900)
• [FIX] Gradle plugin: set org.gradle.category attribute and use reverse DNS naming to avoid name clashes (#6886)
• [FIX] Fix validation of @oneOf input objects. (#6894)
• [DOWNGRADE] Downgrade compileSdk version to 35 for better compatibility (#6899, #6902)

Many thanks to @eboudrant for the contributions in this release 💙

v4.4.2

Maintenance release that adds a new KMP target and makes it easier to work with the new cache and AGP9.

This version also bumps KGP to 2.2. This is transparent for Android/JVM consumers but requires native/JS/wasm consumers to use KGP 2.2 to compile against 4.4.2.

• [NEW] Add watchosDeviceArm64 (#6892)
• [UPDATE] Upgrade KGP to 2.2 (#6892)
• [FIX] If the new cache is present, do not import @typePolicy and @fieldPolicy (#6896)
• [FIX] Use the same classloader than the one which loaded apollo-gradle-plugin to lookup the AGP version (#6877) (#6893)

New developments happen in the 5.0 alphas.

v5.0.0-alpha.5

5.0.0-alpha.5 is "golden-path" ready ✨! It supports the latest GraphQL experimental features:

• Fragment arguments
• Service capabilities
• onError request parameter
• Field extensions

It also bumps KGP version to 2.3.10. This has no impact for JVM/Android consumers but requires Native/JS/Wasm consumers to compile with Kotlin 2.3.

Many thanks to @abeggsnf for the contributions in this release!

👷‍♂️ All changes

• [NEW] Add fragment-arguments (#6882)
• [NEW] Add support for service capabilities (#6858)
• [NEW] Add support for onError (#6860)
• [NEW] Implement field extensions (#6856, #6867)
• [NEW] Use KGP 2.3.10 (#6873)
• [NEW] Add GraphQLWsProtocol.parseServerMessage() (#6871)
• [NEW] Rework field merging validation (#6875)
• [FIX] Data builders: fix nullable fields of composite type (#6855)
• [FIX] Use the same classloader than the one which loaded apollo-gradle-plugin to lookup the AGP version (#6877)
• [FIX] Use public AGP API for version detection instead of internal class (#6874)

v4.4.1

This version has a single fix for a regression in the Gradle plugin:

• [FIX] Fix ./gradlew download${Service}ApolloSchemaFromIntrospection was crashing due to a bad class relocation (#6863)

v5.0.0-alpha.4

Many thanks @MatthewFolbigg, @scana, and @simonlebras for their contributions to this release!

👷‍♂️ All changes

What's Changed

• [NEW] Add watchosDeviceArm64 target in #6791
• [NEW] Add support for directives on directive definitions in #6803
• [NEW] Add ApolloCall.extensions() in #6834
• [FIX] Do not compute key fields and key args when the Cache compiler plugin is present in #6797
• [FIX] Escape /* and */ in KDocs in #6805
• [FIX] Fix DataBuilders in multi-modules scenarios in #6810
• [FIX] Data Builders: do not build the FakeResolver multiple times in #6811
• [FIX] Gradle Plugin: Avoid eager configuration of Gradle objects in #6820
• [FIX] Rename @link Purpose and Import definitions in #6838
• [FIX] Escape names in equals(), hashCode(), copy(), and toString() in #6843