Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Migrating to Apollo Kotlin 4

From version 3


NOTE

Version 4 is currently under development and this page itself is a work in progress.

3 was a major rewrite of Apollo in Kotlin multiplatform.

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

Apollo Kotlin 4 removes some deprecated symbols. We strongly recommend removing deprecated usages before migrating to version 4.

Automatic migration using the Android Studio/IntelliJ plugin

Apollo Kotlin 4 ships with a companion Android Studio/IntelliJ plugin that automates most of the migration.

It automates most of the API changes but cannot deal with behavior changes like error handling.

We recommend using the plugin to automate the repetitive tasks but still go through this for the details.

Moved artifacts

Over the years, a lot of support functionality was added alongside the apollo-api and apollo-runtime artifacts. While useful, most of this functionality doesn't share the same level of stability and maturity as the core artifacts and bundling them did not make much sense.

Moving forward, only the core artifacts remain in the apollo-kotlin repository and are released together.

Other artifacts are moved to new maven coordinates and GitHub repositories.

Old coordinatesNew coordinatesNew Repository
com.apollographql.apollo3:apollo-compose-support-incubatingcom.apollographql.compose:compose-supportapollographql/apollo-kotlin-compose-support
com.apollographql.apollo3:apollo-compose-paging-support-incubatingcom.apollographql.compose:compose-paging-supportapollographql/apollo-kotlin-compose-support
com.apollographql.apollo3:apollo-cli-incubatingcom.apollographql.cli:apollo-cliapollographql/apollo-kotlin-cli
com.apollographql.apollo3:apollo-engine-ktorcom.apollographql.ktor:apollo-engine-ktorapollographql/apollo-kotlin-ktor-support
com.apollographql.apollo3:apollo-mockservercom.apollographql.mockserver:apollo-mockserverapollographql/apollo-kotlin-mockserver
com.apollographql.apollo3:apollo-normalized-cache-incubatingcom.apollographql.cache:normalized-cache-incubatingapollographql/apollo-kotlin-normalized-cache-incubating
com.apollographql.apollo3:apollo-normalized-cache-api-incubatingcom.apollographql.cache:normalized-cache-incubatingapollographql/apollo-kotlin-normalized-cache-incubating
com.apollographql.apollo3:apollo-normalized-cache-sqlite-incubatingcom.apollographql.cache:normalized-cache-sqlite-incubatingapollographql/apollo-kotlin-normalized-cache-incubating
com.apollographql.apollo3:apollo-runtime-javacom.apollographql.java:clientapollographql/apollo-kotlin-java-support
com.apollographql.apollo3:apollo-rx2-support-javacom.apollographql.java:rx2apollographql/apollo-kotlin-java-support
com.apollographql.apollo3:apollo-rx3-support-javacom.apollographql.java:rx3apollographql/apollo-kotlin-java-support

Those new artifacts also have a new package name. You can usually guess it by removing .apollo3:

// Replace
import com.apollographql.apollo3.mockserver.MockServer
// With
import com.apollographql.mockserver.MockServer

apollo-runtime

Fetch errors do not throw

⚠️ CAUTION

Error handling changes are a behavior change that is not detected at compile time. Usages of execute, toFlow and watch must be updated to the new error handling or changed to their version 3 compat equivalent.

See executeV3 and toFlowV3 for temporary methods to help with the migration.

See nullability for a quick peek at the future of nullability and error handling.

In Apollo Kotlin 3, non-GraphQL errors like network errors, cache misses, and parsing errors were surfaced by throwing exceptions in ApolloCall.execute() and in Flows (ApolloCall.toFlow(), ApolloCall.watch()). This was problematic because it was a difference in how to handle GraphQL errors vs other errors and it was easy to forget catching the exceptions. Uncaught network errors is by far the number one error reported by the Google Play SDK Index. Moreover, throwing terminates a Flow and consumers would have to handle re-collection.

In Apollo Kotlin 4, a new ApolloResponse.exception has been added and these errors are now surfaced by returning (for execute()) or emitting (for Flows) an ApolloResponse with a non-null exception instead of throwing it.

This allows consumers to handle different kinds of errors at the same place, and it prevents Flows from being terminated.

Queries and :

// Replace
try {
val response = client.query(MyQuery()).execute()
if (response.hasErrors()) {
// Handle GraphQL errors
} else {
// No errors
val data = response.data
// ...
}
} catch (e: ApolloException) {
// Handle network error
}
// With
val response = client.query(MyQuery()).execute()
if (response.data != null) {
// Handle (potentially partial) data
} else {
// Something wrong happened
if (response.exception != null) {
// Handle non-GraphQL errors
} else {
// Handle GraphQL errors in response.errors
}
}

:

// Replace
client.subscription(MySubscription()).toFlow().collect { response ->
if (response.hasErrors()) {
// Handle GraphQL errors
}
}.catch { e ->
// Handle network error
}
// With
client.subscription(MySubscription()).toFlow().collect { response ->
val data = response.data
if (data != null) {
// Handle (potentially partial) data
} else {
// Something wrong happened
if (response.exception != null) {
// Handle non-GraphQL errors
} else {
// Handle GraphQL errors in response.errors
}
}
}

Note that this is true for all Flows, including watchers. If you don't want to receive error responses, filter them out:

// Replace
apolloClient.query(query).watch()
// With
apolloClient.query(query).watch().filter { it.exception == null }

ApolloCompositeException is not thrown

When using the cache, Apollo Kotlin 3 threw ApolloCompositeException if no response could be found. For an example, a CacheFirst fetch policy would throw ApolloCompositeException(cacheMissException, apolloNetworkException) if both cache and network failed.

In those cases, Apollo Kotlin 4 throws the first exception and adds the second as a suppressed exception:

// Replace
if (exception is ApolloCompositeException) {
val cacheMissException = exception.first
val networkException = exception.second
}
// With
val cacheMissException = exception
val networkException = exception.suppressedExceptions.firstOrNull()

For more control over the exception, use toFlow() and collect the different ApolloResponse.

emitCacheMisses(Boolean) is removed

In Apollo Kotlin 3, when using the normalized cache, you could set emitCacheMisses to true to emit cache misses instead of throwing.

In Apollo Kotlin 4, this is now the default behavior and emitCacheMisses has been removed.

With the CacheFirst, NetworkFirst and CacheAndNetwork policies, cache misses and network errors are now emitted in ApolloResponse.exception.

Migration helpers

To ease the migration from Apollo Kotlin 3, drop-in helpers functions are provided that restore the version 3 behavior:

  • ApolloCall.executeV3()
  • ApolloCall.toFlowV3()

Those helper functions:

  • throw on fetch errors
  • make CacheFirst, NetworkFirst and CacheAndNetwork policies ignore fetch errors.
  • throw ApolloComposite exception if needed.

Because of the number of different options in version 3 and the complexity of error handling, these functions may not 100% match the version 3 behavior, especially in the advanced cases involving watchers. If you are in one of those cases, we strongly recommend using the version 4 functions that are easier to reason about.

Non standard HTTP headers are not sent by default

X-APOLLO-OPERATION-NAME and X-APOLLO-OPERATION-ID are non-standard headers and are not sent by default anymore. If you used them for logging purposes or if you are using CSRF prevention, you can add them back using an ApolloInterceptor:

val apolloClient = ApolloClient.Builder()
.serverUrl(mockServer.url())
.addInterceptor(object : ApolloInterceptor {
override fun <D : Operation.Data> intercept(request: ApolloRequest<D>, chain: ApolloInterceptorChain): Flow<ApolloResponse<D>> {
return chain.proceed(request.newBuilder()
.addHttpHeader("X-APOLLO-OPERATION-NAME", request.operation.name())
.addHttpHeader("X-APOLLO-OPERATION-ID", request.operation.id())
.build()
)
}
})
.build()

ApolloCall.Builder.httpHeaders is additive

In Apollo Kotlin 3, if HTTP headers were set on an ApolloCall, they would replace the ones set on ApolloClient. In Apollo Kotlin 4 they are added instead by default. To replace them, call ApolloCall.Builder.ignoreApolloClientHttpHeaders(true).

// Replace
val call = client.query(MyQuery())
.httpHeaders(listOf("key", "value"))
.execute()
// With
val call = client.query(MyQuery())
.httpHeaders(listOf("key", "value"))
.ignoreApolloClientHttpHeaders(true)
.execute()

HttpEngine implements Closeable

HttpEngine now implements Closeable and has its dispose method renamed to close. If you have a custom HttpEngine, you need to implement close instead of dispose.

apollo-gradle-plugin

Multi-module dependsOn

In Apollo Kotlin 3, you could depend on an upstream GraphQL module by using the apolloMetadata configuration.

In Apollo Kotlin 4, this is now done with the Service.dependsOn(). This allows better management of dependencies when multiple services are used as better symmetry with isADependencyOf below.

// feature1/build.gradle.kts
// Replace
dependencies {
// ...
// Get the generated schema types (and fragments) from the upstream schema module
apolloMetadata(project(":schema"))
// You also need to declare the schema module as a regular dependency
implementation(project(":schema"))
}
// With
dependencies {
// ...
// You still need to declare the schema module as a regular dependency
implementation(project(":schema"))
}
apollo {
service("service") {
// ...
// Get the generated schema types (and fragments) from the upstream schema module
dependsOn(project(":schema"))
}
}

Auto-detection of used types

In multi-module projects, by default, all the types of an upstream module are generated because there is no way to know in advance what types are going to be used by downstream modules. For large projects this can lead to a lot of unused code and an increased build time.

To avoid this, in Apollo Kotlin 3 you could manually specify which types to generate by using alwaysGenerateTypesMatching. In Apollo Kotlin 4 this can now be computed automatically by detecting which types are used by the downstream modules.

To enable this, add the "opposite" link of dependencies with isADependencyOf().

// schema/build.gradle.kts
// Replace
apollo {
service("service") {
// ...
// Generate all the types in the schema module
alwaysGenerateTypesMatching.set(listOf(".*"))
// Enable generation of metadata for use by downstream modules
generateApolloMetadata.set(true)
}
}
// With
apollo {
service("service") {
// ...
// Enable generation of metadata for use by downstream modules
generateApolloMetadata.set(true)
// Get used types from the downstream module1
isADependencyOf(project(":feature1"))
// Get used types from the downstream module2
isADependencyOf(project(":feature2"))
// ...
}
}

If you were using apolloUsedCoordinates, you can also remove it:

dependencies {
// Remove this
apolloUsedCoordinates(project(":feature1"))
}

Publishing is no longer configured automatically

Apollo artifacts are not automatically published anymore. To publish them, create a MavenPublication:

publishing {
publications {
create("apollo", MavenPublication::class.java) {
from(components["apollo"])
artifactId = "${project.name}-apollo"
}
}
}

Custom scalars declaration

customScalarsMapping is removed and replaced with mapScalar() which makes it easier to map to built-in types and/or provide a compile type adapter for a given type:

// Replace
customScalarsMapping.set(mapOf(
"Date" to "kotlinx.datetime.LocalDate"
))
// With
mapScalar("Date", "kotlinx.datetime.LocalDate")
// Replace
customScalarsMapping.put("MyLong", "kotlin.Long")
// With
mapScalarToKotlinLong("MyLong")

schemaFile is deprecated

Because there might be several schema files, schemaFile is deprecated. Instead use schemaFiles:

// replace
schemaFile.set("src/main/graphql/com/example/schema.graphqls")
// with
schemaFiles.from("src/main/graphql/com/example/schema.graphqls")

If you are using packageNamesFromFilePaths and schemaFile, you'll need to use a Gradle FileTree to carry the appropriate normalized path.

packageNameFromFilePaths()
// replace
schemaFile.set("src/main/graphql/com/example/schema.graphqls")
// with
schemaFiles.from(fileTree("src/main/graphql/").apply {
include("com/example/schema.graphqls")
})

NOTE

Apollo Kotlin 3 was using the root directories to compute the schema normalized path which could be wrong in some edge cases. Using fileTree ensures the normalized path is consistent.

Migrating to ApolloCompilerPlugin

Apollo Kotlin 4 introduces ApolloCompilerPlugin as a way to customize code generation. ApolloCompilerPlugin are loaded using the ServiceLoader API and run in a separate classloader from your Gradle build. As a result, using Service.operationIdGenerator/Service.operationOutputGenerator together with ApolloCompilerPlugin is not possible.

Service.operationIdGenerator/Service.operationOutputGenerator are deprecated and will be removed in a future release. You can migrate to ApolloCompilerPlugin using the instructions from the dedicated page and the ApolloCompilerPlugin.operationIds() method:

// Replace (in your build scripts)
val operationOutputGenerator = object: OperationOutputGenerator {
override fun generate(operationDescriptorList: Collection<OperationDescriptor>): OperationOutput {
return operationDescriptorList.associateBy {
it.source.sha1()
}
}
override val version: String = "v1"
}
// Or, if using OperationIdGenerator, replace
val operationIdGenerator = object: OperationIdGenerator {
override fun apply(operationDocument: String, operationName: String): String {
return operationDocument.sha1()
}
override val version: String = "v1"
}
// With (in your build compiler plugin module)
class MyPlugin: ApolloCompilerPlugin {
override fun operationIds(descriptors: List<OperationDescriptor>): List<OperationId>? {
return descriptors.map {
OperationId(it.source.sha1(), it.name)
}
}
}

Operation manifest file location

Since Apollo Kotlin now supports different operation manifest formats, the operationOutput.json file will be generated in "build/generated/manifest/apollo/$service/operationOutput.json" instead of "build/generated/operationOutput/apollo/$service/operationOutput.json".

useSchemaPackageNameForFragments is removed

This was provided for compatibility with 2.x and is now removed. If you need specific package names for , you can use a compiler plugin and ApolloCompilerPlugin.layout() instead.

apollo-compiler

"compat" codegenModels is removed

The "compat" codegen models was provided for compatibility with 2.x and is now removed. "operationBased" is more consistent and generates less code:

// Replace
apollo {
service("service") {
codegenModels.set("compat")
}
}
// With
apollo {
service("service") {
codegenModels.set("operationBased")
}
}

In the generated models, inline fragments accessors are prefixed with on:

// Replace
data.hero.asDroid
// With
data.hero.onDroid

The fragments synthetic property is not needed anymore:

// Replace
data.hero.fragments.heroDetails
// With
data.hero.heroDetails

Finally some that were merged from inline fragments in their parents must now be accessed through the inline fragment:

// Replace
/**
* {
* hero {
* # this condition is always true
* # allowing to merge the name field
* ... on Character {
* name
* }
* }
* }
*/
data.hero.name
// With
/**
* name is not marged anymore
*/
data.hero.onCharacter?.name

NOTE

The Android Studio plugin provides a compat to operationBased migration tool which automates a lot of these changes.

Test builders are removed

Test builders were an experimental feature that have been superseded by data builders, a simpler version that also plays nicer with custom .

In Apollo Kotlin 4, test builders are no longer available - please refer to the data builders documentation for more information.

Enum class names now have their first letter capitalized

For consistency with other types, GraphQL enums are now capitalized in Kotlin. You can restore the previous behavior using @targetName:

# Make sure `someEnum` isn't renamed to `SomeEnum`
enum someEnum @targetName(name: "someEnum"){
A
B
}

__Schema is in the schema subpackage

When using the generateSchema option, to avoid a name clash with the type of the same name, the __Schema type is now generated in a schema subpackage (instead of type):

// Replace
import com.example.type.__Schema
// With
import data.builders.schema.__Schema

KotlinLabs directives are now at version 0.3

The embedded kotlin_labs are now at version 0.3.

These are the client directives supported by Apollo Kotlin. They are imported automatically but if you relied on an explicit import for renames or another reason, you'll need to bump the version:

# Replace
extend schema @link(url: "https://specs.apollo.dev/kotlin_labs/v0.1/", import: ["@typePolicy"])
# With
extend schema @link(url: "https://specs.apollo.dev/kotlin_labs/v0.3/", import: ["@typePolicy"])

This is a backward compatible change.

Directive usages are validated and require a matching directive definition

In Apollo Kotlin 4, all usages are validated against their definition. If you have queries using client side directives:

query HeroName {
hero {
# WARNING: '@required' is not defined by the schema
name @required
}
}

Those queries now required to have a matching directive definition in the schema. If the directive is a server directive, and you downloaded your schema using introspection, the directive definition should be present.

In some cases, for client directives and/or if you did not use introspection, the directive definition might be missing. For those cases, you can add it explicitely in a extra.graphqls file:

directive @required on FIELD

Sealed class UNKNOWN__ constructors are private

When generating enums as sealed classes with the sealedClassesForEnumsMatching option, the UNKNOWN__ constructor is now generated as private, to prevent its accidental usage.

It is recommended to update your schema instead of instantiating an UNKNOWN__ value, but if you need to, use the safeValueOf method instead:

// Replace
val myEnum = MyEnum.UNKNOWN__("foo")
// With
val myEnum = MyEnum.safeValueOf("foo")

apollo-normalized-cache

Configuration order

The normalized cache must be configured before the auto , configuring it after will now fail (see https://github.com/apollographql/apollo-kotlin/pull/4709).

// Replace
val apolloClient = ApolloClient.Builder()
.serverUrl(...)
.autoPersistedQueries(...)
.normalizedCache(...)
.build()
// With
val apolloClient = ApolloClient.Builder()
.serverUrl(...)
.normalizedCache(...)
.autoPersistedQueries(...)
.build()

apollo-ast

The AST classes (GQLNode and subclasses) as well as Introspection classes are not data classes anymore (see https://github.com/apollographql/apollo-kotlin/pull/4704/). The class hierarchy has been tweaked so that GQLNamed, GQLDescribed and GQLHasDirectives are more consistently inherited from.

GQLSelectionSet and GQLArguments are deprecated and removed from GQLField and GQLInlineFragment. Use .selections directly

GQLInlineFragment.typeCondition is now nullable to account for inline fragments who inherit their type condition.

SourceLocation.position is renamed to SourceLocation.column and is now 1-indexed. GQLNode.sourceLocation is now nullable to account for the cases where the nodes are constructed programmatically.

It is not possible to create a Schema from a File or String directly anymore. Instead, create a GQLDocument first and convert it to a schema with toSchema().

apollo-rx{2-3}-support

The apollo-rx2-support and apollo-rx3-support artifacts are deprecated.

They were very thin wrappers around kotlinx-coroutines-rx2 or kotlinx-coroutines-rx3 and will be removed in a future version.

Use kotlinx-coroutines-rx${version} directlyl instead. Replace the artifact in your build script:

dependencies {
// Replace
implementation("com.apollographql.apollo3:apollo-rx2-support:$version")
// With
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-rx2:$version")
}

In your code, use asFlowable():

// Replace
apolloClient.query().rxFlowable()
// With
apolloClient.query().toFlow().asFlowable()
// Replace
apolloClient.query().rxSingle()
// With
apolloClient.query().toFlow().asFlowable().firstOrError()

apollo-idling-resource

ApolloIdlingResource is deprecated. We recommend using reactive patterns to test your UI instead. See this article about ways to do so for more details.

Example of a migration

If you are looking for inspiration, we updated the version 3 integration tests to use version 4. If you have an open source project that migrated, feel free to share it and we'll include it here.

Previous
Get Started
Next
0. Introduction
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company