v5.1.0

Version 5.1.0 adds a lot of performance improvements courtesy of @AlexanderGH on top a bugfix from @dhritzkiv and a couple other things. Many thanks Daniel and Alexander! 💙

👷‍♂️ All changes

• [PERFORMANCE] compiler: index the type hierarchy and drop O(n^2) work from the schema checks (#6994)
• [PERFORMANCE] compiler: skip the @defer walk and index field definitions (#6995)
• [PERFORMANCE] api: faster enum safeValueOf and cheaper knownEntries (#7009)
• [PERFORMANCE] api: Test a fragment's type condition against a set, not a list (#7001)
• [PERFORMANCE] api: stop using exceptions to guess JSON number types (#6996)
• [UPGRADE] Bump cache to 1.0.6 (#6987)
• [FIX] Fix CatchToResult toJson (#6984)
• [FIX] Make it possible to use the new cache with Apollo Kotlin 5 on K/N (#6978)

5.0.1

A few bugfixes, support for onError, and promote "directives on directives" which was merged in the specification recently.

Experimental onError support

If your server supports the onError request parameter, you can now use it to control error propagation:

val response = apolloClient.query(FooQuery())
                .onError(OnError.NULL)
                .execute()

When using OnError.NULL, error propagation is disabled, meaning you get more partial data:

type Query {
  user: User
}

type User {
  name: String!
  email: String!
}

If an error occurs at user.email, you will get a partial response with user.name but no user.email, instead of propagating the error to the parent user field:

{
  "errors": [{"path": ["user", "email"] }],
  "data": {
    "user": {
      "name": "John Doe",
      "email": null
    }
  }
}

Coupled with error aware parsing, it allows for more granular error handling.

Note: onError achieves the same functionality as @experimental_DisableErrorPropagation. It is expected that onError ultimately replaces the directive.

👷‍♂️ All changes

• [compiler] Add missing dependency on kotlinx-serialization-core (#6973)
• [compiler] Exclude invalid fields from field merging validation, fixes validation could hang on some invalid operations (#6972)
• [runtime] Expose a proper [JsonDataException] in case null is returned in an unexpected position (#6971)
• [runtime] Add NullableLongAdapter (#6968)
• [runtime] Add ApolloClient support for onError (#6963)
• [runtime] Fix bug with duplicate headers being added when using batching (#6961)
• [runtime] Deprecate allowDirectivesOnDirectives, it is now merged (#6965)
• [runtime] Fix allowDirectivesOnDirectives not being honored (#6953)
• [runtime] Workaround introspection for servers that do not support isOneOf despite advertizing it (#6949)

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)