v4.0.0

Apollo Kotlin 4 is a maturity release. It focuses on tooling, stability and making the library more maintainable, so it can evolve smoothly for the many years to come.

While most of the core APIs stayed the same, Apollo Kotlin 4 contains a few binary breaking changes. To account for that, and in order to be more future-proof, we changed the package name to com.apollographql.apollo.

You need to replace all the com.apollographql.apollo3 with com.apollographql.apollo in your codebase.

• Migration guide: https://www.apollographql.com/docs/kotlin/migration/4.0.
• Evolution policy: https://www.apollographql.com/docs/kotlin/essentials/evolution.

Thanks again to everyone who provided feedback during the alphas/betas.

Main changes

• New package name (migration guide)
• Moved artifacts (Apollo Kotlin galaxy documentation page)
• Improved error handling (migration guide)
• Android Studio/IntelliJ Plugin (installation instructions)
• Multiplatform GraphQL parser (doc)
• Apollo Compiler Plugin API (doc)
• WasmJs support
• NetworkMonitor API (doc)
• Experimental WebSocket API (doc)
• Experimental support for @oneOf (GraphQL RFC)
• Experimental support for @semanticNonNull and @catch (doc)

Changes against 3.8.5

• #5984 - Add doNotStoreOnDisk()
• #5982 - RetryOnNetworkErrorInterceptor should be configurable
• #5971 - writeOperation/writeFragment no longer publish updates by default
• #5966 - Move apollo-execution out of the main repo
• #5952 - [IJ Plugin] Cache GraphQL project config
• #5946 - Sub-protocol not included when opening websocket [4.0.0-beta6]
• #5933 - [IJ/AS plugin] Internal error: NullPointerException
• #5929 - Unnecessary AndroidX Multidex library included
• #5922 - Apply com.apollographql.apollo3 plugin will break the dependencies in Kotlin Multiplatform according to IDEA
• #5917 - Enabling apollo metadata generation for multi-module codegen causes build cache misses
• #5901 - A request with any enum having rawValue = null hangs forever
• #5899 - [IJ Plugin] UI for 'Go to declaration' is too wide
• #5896 - [IJ Plugin] Cache viewer icon has wrong color in "new ui" theme
• #5887 - [IJ Plugin] Warn when .graphqlrc files are present
• #5885 - Cronet request lifecycle not behaving correctly with Apollo.
• #5884 - [IJ/AS plugin] Internal error: NullPointerException
• #5834 - SQL cache is unusably slow
• #5833 - Make apollo-mockserver a separate repository
• #5832 - MegaIssue: Independant versioning
• #5827 - [IJ Plugin] Incorrect error when repeating @semanticNonNullField
• #5819 - "Could not read normalized cache" in AS plugin
• #5808 - Support for tree shaking in the __Schema.possibleTypes()
• #5801 - ClassCastException is thrown when building an ApolloClient using a builder in KotlinJS
• #5799 - isFromCache is potentially confusing
• #5796 - Make it impossible to pass as input some type which was generated only to preserve forwards compatibility but was not meant to be used as input
• #5795 - WasmJs support for apollo-adapters
• #5781 - Codegen: rework how compiled field arguments are generated
• #5777 - ApolloClient.Builder.okHttpClient() returns null instead of this
• #5775 - Lazy version of okHttpCallFactory?
• #5771 - [IJ Plugin] Crash when navigating to GraphQL operation via margin marker
• #5768 - [IJ/AS plugin] Internal error: NullPointerException
• #5757 - ApolloParseException is wrapping SocketException, StreamResetException
• #5753 - [IJ/AS plugin] Internal error: NullPointerException
• #5745 - Run subscriptions like queries with IDE plugins
• #5738 - [IJ Plugin] Tweak navigation from GraphQL to generated code
• #5727 - [Intellij Plugin] Truncate "go to" data
• #5723 - Remove sendApqExtensions and sendDocument from MutableExecutionOptions
• #5715 - Make NetworkMonitor work without androidx.startup
• #5714 - Upgrade IJ platform minVersion
• #5713 - Make benchmarks a composite build
• #5712 - generateServiceApolloSources task fails with nondescript NullPointerException when type extension references unknown key field
• #5697 - Websocket won't reopen on iOS
• #5667 - Experimental @defer support does not work with AutoPersistedQueryInterceptor
• #5659 - Use StreamingNSURLSessionHttpEngine by default on Apple
• #5648 - Megaissue: improvements to WebSockets
• #5647 - [IJ Plugin] Try the new IntelliJ Platform Gradle Plugin 2.0
• #5641 - Introspection is broken in the beta
• #5616 - [IJ Plugin] Send telemetry only for projects using Apollo
• #5575 - [IJ/AS plugin] Internal error: Throwable
• #5568 - Disallow @typePolicy on unions
• #5507 - 🧩 [IJ Plugin] Remove client only directives before sending the query to the server
• #5500 - [IJ Plugin] v3 -> v4 Migration: add @link imports for used kotlin_labs directives
• #5481 - [IJ/AS plugin] Internal error: ClassCastException
• #5468 - Publish apollo-cli
• #5455 - Build fails after schema file rename when Gradle configuration cache enabled
• #5449 - [gradle-plugin] download{Service}SchemaFromIntrospection fails
• #5431 - Support @oneOf for Input Objects
• #5415 - Compiler plugin API + classloader isolation
• #5413 - [IJ plugin] Automatically import certain directives
• #5379 - Allow the cache viewer to sort items more "intelligently" when showing cache entries that have a number at the end
• #5374 - [IJ Plugin] Inspection to warn when using input types constructors
• #5372 - [IJ plugin] Normalized cache: reload button for file caches
• #5345 - [RFC] Remove X...

v4.0.0-rc.2

We're on the road to v4 with this second release candidate which includes a few minor tweaks as well as one new feature.

Note: in v4.0.0-rc.1 apollo-debug-server and apollo-tooling depended on com.apollographql.apollo3 artifacts. This is no longer the case with v4.0.0-rc.2, where all dependencies are under the com.apollographql.apollo group id.

Add memoryCacheOnly (#6049)

.memoryCacheOnly(true) can be set on calls to read and store records in the memory cache only even when a persistent cache is configured.
This can be useful in scenarios where long term storage isn't needed and performance is important.

• [gradle-plugin] Use a better warning for Service.schemaFile users (#6036)
• [all] Update apollo-kotlin-execution (#6040)
• [IJ Plugin] Add com.apollographql.apollo:apollo-api-jvm to dependencySupport (#6039)
• [all] Update to Gradle 8.9 (#6056)
• [gradle-plugin] Undeprecate schemaFile (#6055)
• [gradle-plugin] Disable service-loading ApolloCompilerPlugin (#6059)

v3.8.5

Version 3.8.5 is a maintenance release. New developments happen in the 4.x versions.

• [all] Bump okio to 3.9.0 (#5868)
• [runtime] Adding checks for json end_document in http transport (#5894)
• [runtime] Adding checks for json end_document in http batching interceptors (#5892)
• [codegen] Fix mapping of the builtin Float scalar type (#6047)
• [normalized-cache] SqlNormalizedCacheFactory make sqldriver public to support Sqlcipher data encryption. (#5972)

v4.0.0-rc.1

New package name & evolution policy

We changed the package name from com.apollographql.apollo3 to com.apollographql.apollo for version 4. This is a safe default for the many years to come and works well with our new evolution policy.

If you are updating from version 3 or an alpha/beta version 4, you need to replace all com.apollographql.apollo3 with com.apollographql.apollo

Apollo galaxy

As part of this release, some of the non-core artifacts have been moved to separate coordinates and GitHub repositories. Moving forward, this will allow us to iterate faster on those artifacts while keeping the core ones more maintainable.

Some of the existing symbols are kept as deprecated to ease the transition (like MockServer for an example). Others (the -incubating ones) have been removed, and you need to update them now.

You can read more in the migration guide.

All changes

• [BREAKING][all] Change package name to com.apollographql.apollo
• [BREAKING][all] Remove incubating compose support (moved to a separate repo, see migration guide)(#5987)
• [BREAKING][all] Remove incubating apollo-cli (moved to a separate repo, see migration guide)(#5986)
• [BREAKING][all] Remove incubating normalized cache (moved to a separate repo, see migration guide)(#5985)
• [BREAKING][all] Nullability: update nullability directives to v0.4 (#6002)
• [BREAKING][all] Suffix ApolloStore write/publish overloads with Sync to avoid them taking precedence over their suspend counterparts (#5976)
• [NEW][cache] SqlNormalizedCacheFactory make sqldriver public to support Sqlcipher data encryption. (#5973)
• [NEW][runtime] Add ApolloClient.Builder.retryOnErrorInterceptor (#5989)
• [adapters] Deprecate apollo-adapters (moved to a separate repo, see migration guide)(#6012)
• [mockserver] Deprecate com.apollographql.apollo3.mockserver.MockServer (moved to a separate repo, see migration guide)(#5943)
• [🐘gradle-plugin] Rename the multi-module configurations (#6027)
• [IJ Plugin] Tweak cache name display for Apollo 3, 4, and incubating (#6026)
• [compiler] remove unused argument to scalarAdapterInitializer() (#5996)
• [java] Use published version of the Java support libs (#5991)
• [runtime] Deprecate apollo engine ktor and publish engine tests (#5988)
• [mpp-utils] Cleanup mpp utils (#5980)
• [CI] use gradle/actions/setup-gradle instead of gradle-build-action (#5981)
• [infra] Update to develocity API (#5967)
• [incubating cache] Add a CacheKeyApolloResolver based on ApolloResolver (incubating) (#5970)
• [mockserver] Robustify TCP server (#5968)
• [runtime] adding checks for json end_document in http batching interceptors (#5893)
• [IJ plugin] Cache ApolloKotlinService into project settings (#5962)
• [IJ plugin] Avoid a ConcurrentModificationException occurring in conjunction to the IJ Platform Gradle plugin. (#5959)
• [websockets] Send Sec-WebSocket-Protocol (#5948)

v4.0.0-beta.7

Main changes:

• #5931: This version is built with K2. You need Kotlin 1.9+ on the JVM to build against it and Kotlin 2.0 for other platforms.
• #5865: ApolloCompilerPluginProvider is introduced to allow passing arguments to compiler plugins. See the compiler plugins documentation for more details.

👷‍ All changes

[testing] Use com.apollographql.mockserver.MockServer (#5939)
[testing] Simplify our implementation of runTest (#5935)
[testing] Prepare apollo-testing-support to new MockServer (#5934)
[runtime] Remove multidex library (#5930)
[all] Bump languageVersion/apiVersion to Kotlin 2.0 (#5931)
[codegen] fix mapping of the builtin Float type (#5928)
[IJ Plugin] Add inspection to warn about the presence of a GraphQL config file (#5908)
[codegen] Add a null-check to java enum safeValueOf (#5904)
[gradle-plugin] Remove eager configuration (#5923)
[gradle-plugin] sort input files (#5919)
[IJ Plugin] Suppress GraphQLDuplicateDirective for certain directives (#5910)
[adapters] Add KtorHttpUrlAdapter (#5915)
[IJ Plugin] Add a "new UI" compatible icon (#5906)
[IJ Plugin] Operation and fragment definition rename (#5912)
[IJ Plugin] Add @link directives to extra.graphqls during v3->v4 migration (#5909)
[IJ Plugin] Remove GraphQL IJ plugin issue workaround (#5907)
[cache] Pagination: use "field key" instead of "field name" (#5898)
[IJ Plugin] Improve the presentation of GraphQL elements when navigating to them (#5900)
[IJ Plugin] Include subfolders when contributing GraphQL config (#5871)
[runtime] Remove existing interceptors from ApolloClient.Builder before adding new ones (#5858)
[codegen] Add ApolloCompilerPluginProvider (#5865)
[runtime] Clear current ApolloStore related interceptors when calling .store() on builder (#5857)
[cache] Call through to loadRecords from the MemoryCache to the SQL one (#5848)
[runtime] deprecate operationIdGenerator (#5850)

v3.8.4

Version 3.8.4 is a maintenance release with one bug fix and 2 performance improvements. New developments happen in the 4.x versions.

• [java-runtime] Fix ApolloClient.Builder.okHttpClient() returns null instead of this (#5860)
• [normalized-cache] Use a single transaction when using MemoryCache chaining (#5861)
• [normalized-cache] Call through to loadRecords from the MemoryCache to the SQL one (#5863)

v4.0.0-beta.6

SQL cache performance improvements

If you're using a chained memory + SQL cache, #5840 makes sure cache writes are wrapped in a transaction, making them much faster.

Apollo Compiler Plugins

Plugin is renamed to ApolloCompilerPlugin. There is a new documentTransform API as well as other fixes. More details in the compiler plugins documentation.

Experimental WebSockets

A new .websocket package is available that makes it easier to retry WebSockets and handle errors. More details and migration guide in the experimental websockets documentation.

ApolloIdlingResource is deprecated

We recommend using reactive patterns to test your UI instead. See this article about ways to do so.

Removed androidx.startup dependency

androidx.startup was introduced in beta.5 but is problematic for unit tests and other cases. beta.6 removes that dependency. More details in the network connectivity documentation.

WasmJS support for apollo-adapter

You can see Wasm in action at https://wasm.confetti-app.dev/

Threading changes

In a effort to minimize the number of thread switches, the whole request is now run in the same dispatcher. See Threading.md for more details.

Contributors 💙

Many thanks to @joreilly, @ychescale9 and @japhib for their contributions to this release 💙!

👷‍ All changes

• [normalized-cache]: use a single SQL transaction when using MemoryCache chaining (#5840)
• [compiler] expose apollo-ast as an api dependency (#5838)
• [compiler] Rename Plugin to ApolloCompilerPlugin and add error message for bad configurations (#5821)
• [IJ Plugin] Fix pulling file from device not working on AS Koala (#5822)
• [compiler] Add @ApolloEnumConstructor and make enum as sealed class Unknown constructor opt-in (#5813)
• [runtime] Move ApolloParseException to ApolloNetworkException (#5816)
• [normalized-cache] Let isFromCache be about the ApolloResponse (#5805)
• [compiler] Add DocumentTransform API (#5809)
• [idling-resource] Deprecate ApolloIdlingResource (#5817, #5764)
• [runtime] Share the default OkHttpBuilder (#5811)
• [runtime] [BREAKING] change isOnline to a suspend fun
• [adapters] Support Kotlin/Wasm for apollo-adapters (#5803)
• [all] Bump Kotlin to 2.0.0-RC1 (#5802)
• [Codegen] Add CompiledArgumentDefinition (#5797, #5837)
• [runtime] Merge experimental WebSocketNetworkTransport in apollo-runtime (#5790)
• [normalized-cache] Cache pagination: add FieldNameGenerator and EmbeddedFieldsProvider (#5772)
• [runtime] Support configuring ApolloClient with lazily initialized Call.Factory. (#5784)
• [runtime] fix ApolloClient.Builder.okHttpClient() returns null instead of this (#5778)
• [normalized-cache] Fix variable coercion in lists. Absent variables are coerced to null (#5773)
• [IJ Plugin] Fix an NPE (#5770)
• [runtime] Simplify ApolloCall (#5765)
• [runtime] remove androidx.startup dependency (#5761, #5720)
• [compiler] Bump kotlin_labs definitions to v0.3 (#5762)
• [Pagination] Support nodes in Connection types (#5754)
• [compiler] Directive validation is now enforced by default (#5758)
• [cache] Make ApolloStore.publish() suspend (#5755)
• [runtime] Change the dispatcher earlier in the chain (#4319)
• [IJ Plugin] Add an advanced setting to include generated code references in GraphQL "Go To Declaration" (#5743)
• [IJ Plugin] Fix presentation of Kotlin elements when navigating to them from GraphQL (#5739)
• [IJ Plugin] Consider all Gradle projects recursively (#5734)
• [runtime] Deprecate ApolloClient.Builder.addInterceptors() (#5733)
• [all] use jdk-release (#5731)
• [http-cache] Ignore IOException when calling ApolloHttpCache.remove (#5729)
• [IJ plugin] Bump platformVersion and pluginSinceBuild from 232 to 233 (#5726)
• [runtime] add ApolloClient.failFastIfOffline (#5725)
• [all] Introduce "filesystem" sourceSet and use okio 3.9.0 (#5719)
• [runtime] Do not use Ktor in Js HttpEngine, use fetch directly instead (#5702)

v3.8.3

Version 3.8.3 is a maintenance release with two new convenience APIs and a Kotlin update. New developments happen in the 4.x versions.

Note: because Apollo Kotlin now depends on kotlin-stdlib version 1.9, you need the 1.8+ Kotlin compiler to compile your project.

• [all] update Kotlin to 1.9 (#5412)
• [runtime] Add ApolloClient.Builder(ApolloHttpCache) (#5638) (#5640)
• [runtime] Allow buildPostBody to write operation extensions (#5631)
• [runtime] compose support: Catch exceptions and expose them in .exception (#5018)
• [http-cache] Ignore IOException when calling ApolloHttpCache.remove (#5730)
• [all] Add deprecations on symbols that are getting removed in v4 (#5746)

v4.0.0-beta.5

Main changes:

• Apollo compiler plugins: The GraphQL compiler now has APIs that you can use to customize the generated code. This can be used for changing visibility of some symbols, renaming them or more generally customizing the output for any advanced use cases. Moving forward, Apollo compiler plugins are the preferred way to customize operation IDs as well as package names and both PackageNameGenerator and OperationOutputGenerator are deprecated. See the documentation page about Apollo compiler plugins for more details.
• Reduced lock contention in apollo-normalized-cache-incubating: the incubating normalized cache now uses lock-free memory structures inspired by guava and MobileNativeFoundation/Store. We have seen improvements by up to 20% in some scenarios. Please share your numbers if you notice any positive (or negative) change.
• Nullability directives: The version of the supported nullability directives was bumped from 0.1 to 0.3 (See apollographql/specs#42 and apollographql/specs#48). If you are using @semanticNonNull or @catch you should bump your @link directives to use 0.3. See the nullability documentation page for more details.
• New snapshot repository for the IntelliJ/Android Studio plugin: The repository to use for the weekly snapshots has changed. You can now use https://go.apollo.dev/ij-plugin-snapshots to get the latest weekly snapshots. (#5600)
• Multi-version KDoc: The published KDoc now includes both v3 and v4 versions.

Many thanks to @ribafish, @molundb, @mboyd1993, @rohandhruva and @baconz for their help in this release 💙!

👷‍ All changes

• [mockserver] Add MockServer.enqueueError() and MockServer.assertNoRequest() (#5694)
• [runtime] Implement NetworkMonitor for apple platforms (#5691)
• [runtime] Add NetworkMonitor (#5690)
• [runtime] Add ApolloClient.retryOnError(Boolean) (#5685)
• [websockets-network-transport-incubating] Publish apollo-websocket-network-transport-incubating (#5693)
• [normalized-cache-incubating] Use Store Cache and merge optimistic cache with Memory cache (#5651)
• [runtime] Fix ApolloClient.Builder if the Builder is mutated by the caller after calling build() (#5683)
• [websockets-network-transport-incubating] Introduce incubating WebSocketNetworkTransport (#5678)
• [websockets-network-transport-incubating] Introduce incubating WebSocketEngine (#5676)
• [runtime] Don't assume a single emission in AutoPersistedQueryInterceptor (#5677)
• [runtime] Use expect funs instead of expect classes for DefaultHttpEngine (#5672)
• [runtime] Fix JS websocket throws an ISE on error on Safari and Firefox (#5670)
• [runtime] Use the streaming HttpEngine by default on Apple (#5671)
• [intellij-plugin] Only send telemetry for Apollo Kotlin projects (#5663)
• [gradle-plugin] Use Gradle normalization instead of ours (#5636)
• [execution] Fix converting int and floats to their Kotlin value (#5637)
• [runtime] Add ApolloClient.Builder(ApolloHttpCache) (#5638)
• [gradle-plugin] Use com.android.lint Gradle rules (#5639)
• [all] Update coroutines to 1.8.0 (#5626)
• [runtime] Allow buildPostBody to write operation extensions (#5630)
• [compiler] Add support for @catch on fieldDefinitions, interfaces and objects (#5623)
• [all] Bump Kotlin to 2.0.0-Beta4 (#5624)
• [normalized-cache-incubating] Cache lock changes (#5608)
• [rx-support] Keep rx-support as DeprecationLevel.Error (#5610)
• [gradle-plugin] Add dependsOn(dependencyNotation, bidirectional) (#5606)
• [gradle-plugin] Fix a regression in alwaysGenerateTypesMatching where all types would be generated by default (#5605)
• [️compiler] Add Apollo compiler plugin API (#5604, #5599, #5591, #5589, #5588, #5582, #5573, #5561, #5560, #5557, #5556, #5554, #5516, #5589)
• [intellij-plugin] Publish the IJ plugin snapshots to the JetBrain Marketplace (#5600)
• [runtime] HTTP Headers: remove X-APOLLO-OPERATION-NAME, X-APOLLO-OPERATION-ID and the multipart boundary (#5533)
• [gradle-plugin] use Worker API and ServiceLoader (#5590)
• [gradle-plugin] deprecate schemaFile and sourceFolder (#5581)
• [gradle-plugin] configuration cache and lazy properties for schema files (#5580)
• [️compiler] Track semanticNonNull spec (#5577)
• [gradle-plugin] bump minimum required Gradle version to 8.0 (#5579)
• [ast] Validate repeatable directives (#5574)
• [compiler] Don't automatically add key fields to union selections (#5562)
• [runtime] Fix disabling batching by default (#5552)
• [gradle-plugin] Select all types in pre-introspection query (#5547)
• [normalized-cache-api] Remove unnecessary suspend from ApolloStore functions (#5541)
• [all] One more step towards K2 but blocked on https://youtrack.jetbrains.com/issue/KT-21846 (#5536)
• [all] Target Java17 for Android .aars and Java11 for apollo-gradle-plugin.jar (#5534)
• [compiler] Remove old generateAsInternal code (#5526)
• [compiler] Lock down apollo-compiler API (#5524)
• [normalized-cache-sqlite] Use windowSizeBytes argument of AndroidSqliteDriver (#5523)
• [intellij-plugin] Strip Apollo client directives before executing operations (#5517)
• [execution] Fix converting GraphQL Float values to Kotlin (#5511)
• [intellij-plugin] Don't show a visible task with progress bar while fetching the Apollo Conf (#5501)
• [intellij-plugin] Inspection: missing directive import (#5494)
• [intellij-plugin] Use recent version of slf4j to avoid a classloader issue (#5495)
• [normalized-cache-sqlite] Allow custom SupportSQLiteOpenHelper.Callback in the SqlNormalizedCacheFactory (#5488)
• [mockserver] Allow to set the content-type of String responses (#5489)
• [debug-server] Start LocalServerSocket on background thread, and handle ...

v4.0.0-beta.4

✨ Initial Wasm support (#5458)

This release adds initial support for WebAssembly by adding the wasmJs target.

Executing queries/mutations is working but this target is
experimental (Kotlin/Wasm is Alpha) and has multiple limitations:

• No WebSockets
• No caching
• No support for WASI or NodeJS

🪲 Bug fix

Downloading a schema from introspection (./gradlew downloadServiceSchemaFromIntrospection) got broken in the previous release (#5449) and is now fixed.

👷‍ All changes

• [compiler] validate operation directives & enforce presence of the nullability directive definitions by @martinbonnin
  in #5443
• [build] Bump okio version by @martinbonnin in #5447
• [build] Bump uuid version by @martinbonnin in #5448
• Fix 2nd step introspection by @BoD in #5451
• Add wasmJs target by @martinbonnin in #5458
• Add validation to check schema definitions are compatible with the bundled ones by @BoD
  in #5444