v4.1.0

Ktor 3.0.0

Version 4.1.0 updates usages of Ktor from 2.3.11 to 3.0.0:

• If you are using apollo-runtime-js or apollo-debug-server-jvm, you need to update your app to Ktor 3.0.0+ at the same time as updating to Apollo 4.1.0 (apollo-debug-server-android is unaffected).
• If you are using the deprecated apollo-mockserver or apollo-ktor-support from this repo, you need to update to the new coordinates.

All other cases are unaffected. In particular, apollo-runtime on Android and iOS uses OkHttp and NsUrlConnection respectively and is not impacted by the Ktor update.

You can read more details in the pull request.

New media type: application/graphql-response+json

application/graphql-response+json is a new media type being introduced by the GraphQL over HTTP draft. It allows differentiating a valid GraphQL response from an error JSON response that could be transmitted by a cache or proxy in the HTTP chain.

If your server uses application/graphql-response+json and returns non-2xx response, Apollo Kotlin will now parse those responses and expose data and errors instead of returning an ApolloHttpException before.

K2 support for the IntelliJ plugin

The IntelliJ plugin is now compatible with K2 (#6150)

Removed apollo-mockserver and apollo-ktor-support

• apollo-mockserver is now at com.apollographql.mockserver:apollo-mockserver:0.1.0 and developed at https://github.com/apollographql/apollo-kotlin-mockserver
• apollo-ktor-support is now at com.apollographql.ktor:apollo-engine-ktor:0.1.0 and developed at https://github.com/apollographql/apollo-kotlin-ktor-support/

👷‍♂️ All changes

• [all] Update kotlinpoet to 2.0.0 (#6215)
• [all] Update to Ktor 3 (#6214)
• [all] Remove apollo-mockserver and apollo-ktor-support (#6215)
• [all] Remove mockserver as a dependency of apollo-testing-support (#6218)
• [ast] Do not escape slashes in single quoted strings (#6190)
• [runtime] Add support for application/graphql-response+json (#6170)
• [runtime] Do not call experimental webSocket() method re-entrently (#6197)
• [debug server] Remove Ktor dependency from apollo-debug-server JVM (#6224)
• [codegen] Do not add internal to private members (#6213)
• [codegen] Fix name clash in data builder names when two types differ only by their case (#6195)
• [gradle plugin] Allow null in KSP arguments for Apollo Compiler Plugins (#6200)
• [gradle plugin] Do not log the full introspection JSON (#6199)
• [gradle plugin] Deprecate TargetLanguage.KOTLIN_1_5 (#6193)
• [IJ Plugin] Make the cache viewer understand the blob db format (#6187)
• [IJ Plugin] Bump IJ Platform Gradle Plugin to 2.0.1 (#6185)
• [IJ Plugin] Migrate to the K2 compatible Analysis API (#6150)
• [IJ Plugin] Schedule the GraphQL configuration reload early (#6228)
• [IJ Plugin] Rename related generated code when renaming an Operation/Fragment (#6227)
• [IJ Plugin] Only highlight the name of unused operations, rather than the whole operation (#6226)

v4.0.1

This release contains a handful of bug fixes and improvements.

⚙️ Add ApolloCompilerPlugin.schemaListener()

The compiler plugins API has been extended to allow listening to schema changes.
This can be used to have plugins generate code based on the schema. To do this, implement the schemaListener
function on your plugin:

class MyCompilerPlugin() : ApolloCompilerPlugin {
  @ApolloExperimental
  override fun schemaListener(): SchemaListener {
    return object : SchemaListener {
      override fun onSchema(schema: Schema, outputDirectory: File) {
        // Generate some code inside outputDirectory based on schema
      }
    }
  }
}

🚀 Allow mapping scalars to simple generic types

Previously, to map a scalar to a generic type, you had to use a typealias.
Now, simple generic types are accepted, and common types like List and String don't need to be fully qualified:

mapScalar("MassList", "List<com.example.Measure<com.example.Mass>>", "com.example.MassListAdapter")

💙 Contributors

Many thanks to @ebrattli, @agrosner and @cvb941 for their contributions to this release 💙!

👷 All changes

• [gradle-plugin] Deprecate "operationOutput" and ./gradlew downloadApolloSchema (#6097)
• [gradle-plugin] Use registerJavaGeneratingTask (#6149)
• [apollo-ast] Add GQLDocument.validate(SchemaValidationOptions) to allow adding external schemas. (#6164)
• [compiler] Add ApolloCompilerPlugin.schemaDocumentListener() (#6165)
• [compiler] Pass schema to ApolloCompilerPlugin.schemaListener (#6166)
• [compiler] Avoid enum value clashing with the getter field (#6093)
• [compiler] Fix a few additional instances of %L used instead of %N (#6117)
• [compiler] Escape properties in input builder function body (#6116)
• [compiler] Provide a more descriptive error message when a resolution of a specific ResolverKey fails (#6136)
• [compiler] Deprecate @nonnull (#6152)
• [compiler] Allow mapping scalars to simple generic types (#6158)
• [tooling] Allow to shutdown SchemaDownloader (#6091)
• [tooling] Remove warning (#6092)
• [WebSockets] connectionParams -> connectionPayload (#6103)
• [WebSockets] add NetworkTransport.closeConnection() (#6105)
• [BREAKING][runtime] Change NetworkMonitor to expose a StateFlow directly (#6119)
• [runtime] Add 'OfflineException' as a cause when using failFastIfOffline (#6104)
• [apollo-api] Fix reading JsonNumber in MapJsonReader (#6141)
• [cache] Allow to store JsonNumber in Record (#6139)
• [cache] Fix cascade SQL cache remove loops forever on cyclic references (#6137)
• [IJ Plugin] Bump pluginUntilBuild to 242 and pluginSinceBuild to 241 (#6111)
• [IJ Plugin] Add ApolloOneOfGraphQLViolationInspection (#6125)
• [IJ Plugin] Improve performance of ApolloGraphQLConfigFilePresentInspection and ApolloGraphQLConfigFilePresentAnnotator (#6126)
• [IJ Plugin] Fix high latency field inspection (#6142)
• [IJ Plugin] Correctly name Open In items (#6151)
• [infra] Bump Kotlin to 2.0.10 (#6107)
• [infra] Bump Kotlin to 2.0.20 (#6131)
• [infra] Bump develocity (#6128)
• [infra] Update Apollo Execution (#6138)
• [infra] Bump develocity (#6144)
• [infra] Allow compiling the project with Java22 (#6145)

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)