Migration guides
Migrate from older versions of Apollo Android
Migrating to 2.x
Kotlin Multiplatform
We are really excited to announce that with this release it is possible to build Kotlin Multiplatform apps with Apollo. The supported targets are Android / iOS / JVM.
Please check-out samples/multiplatform
for sample application.
This is a backward compatible change for existing users. Please keep in mind that it will bring Kotlin standard library as a transitive dependency.
Side effect changes of Kotlin migration:
Some primitive types like
Boolean
s may be unboxed where appropriateClasses and functions are
final
unless they are intentionally marked asopen
Kotlin-stdlib is added as a transitive dependency
Jvm target version is now 1.8. See the Android Developer website for details on how to enable it in yout project.
Okio migration
Okio has been updated to 2.4.3 for Kotlin multiplatform.
The new version of okio is binary compatible. There are some source incompatible changes for Kotlin users like Java static function being moved to Kotlin extension functions.
If you explicitly depend okio, it is recommended to do a major version upgrade before upgrading Apollo.
Note: while we initially considered upgrading Okhttp to version 4.x, we ultimately reverted the change to keep compatibility with Android 4.4. More details in #2054 and 2269 .
New Normalized Cache Modules
For in-memory LruNormalizedCache
users, no change required since apollo-runtime
brings it as transitive dependency. It is still
recommended adding the following dependency explicitly: implementation("com.apollographql.apollo:apollo-normalized-cache:x.y.z")
Apollo normalized cache module (#2142 )
SqlNormalizedCache
is moved to its own module. If you added apollo-android-support
for disk cache, replace it with new dependency.
1// Replace:
2implementation("com.apollographql.apollo:apollo-android-support:x.y.z")
3
4// With:
5implementation("com.apollographql.apollo:apollo-normalized-cache-sqlite:x.y.z") // highlight-line
ApolloSqlHelper
is deprecated. Instantiate SqlNormalizedCacheFactory
with same arguments instead.
1// Replace:
2val apolloSqlHelper = ApolloSqlHelper.create(context, "db_name");
3val cacheFactory = SqlNormalizedCacheFactory(apolloSqlHelper);
4
5// With:
6val cacheFactory = SqlNormalizedCacheFactory(context, "db_name"); // highlight-line
1// Replace:
2ApolloSqlHelper apolloSqlHelper = ApolloSqlHelper.create(context, "db_name");
3NormalizedCacheFactory cacheFactory = new SqlNormalizedCacheFactory(apolloSqlHelper);
4
5// With:
6NormalizedCacheFactory cacheFactory = new SqlNormalizedCacheFactory(context, "db_name"); // highlight-line
Replace legacy Android SQL with SqlDelight (#2158 )
Deprecated Gradle Plugin
The deprecated Gradle Plugin is now removed. Please refer to migration guide from previous releases before upgrading to 2.0 https://www.apollographql.com/docs/android/essentials/migration/#gradle-plugin-changes
Migrating to 1.3.x
Apollo Android version 1.3.0 introduces some fixes and improvements that are incompatible with 1.2.x. Updating should be transparent for simple use cases and your project should compile fine. If you're using more advanced features such as custom schema/graphql files location, Kotlin Gradle scripts and/or transformed queries, or if you encounter a build error after updating, read on for details about the changes.
Gradle plugin changes
The plugin has been rewritten in Kotlin to make it more maintainable and have better support for multiple GraphQL endpoints. Below are the main changes. Read plugin-configuration.md for a reference of the different options.
New plugin ID
The plugin ID has been changed from com.apollographql.android
to com.apollographql.apollo
to make it clear that the plugin works also
for non-Android projects. com.apollographql.android
will be removed in a future revision.
1// Replace:
2apply(plugin = "com.apollographql.android")
3
4// With:
5apply(plugin = "com.apollographql.apollo") // highlight-line
1// Replace:
2apply plugin: 'com.apollographql.android'
3
4// With:
5apply plugin: 'com.apollographql.apollo' // highlight-line
Using multiple services
The plugin now requires that you specify multiple services explicitly. If you previously had the following layout:
1src/main/graphql/com/github/schema.json
2src/main/graphql/com/github/GetRepositories.graphql
3src/main/graphql/com/starwars/schema.json
4src/main/graphql/com/starwars/GetHeroes.graphql
You will need to define 2 services:
1apollo {
2 service("github") {
3 sourceFolder.set("com/github")
4 rootPackageName.set("com.github")
5 }
6 service("starwars") {
7 sourceFolder.set("com/starwars")
8 rootPackageName.set("com.starwars")
9 }
10}
Specifying schema and GraphQL files location
The root schemaFilePath
, outputPackageName
and sourceSets.graphql
are removed and will throw an error if you try to use them. Instead
you can use [CompilationUnit] to control what files the compiler will use as inputs.
1// Replace:
2sourceSets {
3 main.graphql.srcDirs += "/path/to/your/graphql/queries/dir"
4}
5
6// With:
7// highlight-start
8apollo {
9 graphqlSourceDirectorySet.srcDirs += "/path/to/your/graphql/queries/dir"
10}
11// highlight-end
1// Replace
2apollo {
3 sourceSet {
4 schemaFilePath = "/path/to/your/schema.json"
5 exclude = "**/*.gql"
6 }
7 outputPackageName = "com.example"
8}
9
10// With:
11apollo {
12 schemaFile.set(file("/path/to/your/schema.json"))
13 graphqlSourceDirectorySet.exclude("**/*.gql")
14 rootPackageName.set("com.example")
15}
Kotlin DSL
The plugin uses Gradle Properties to support lazy configuration and wiring tasks together.
If you're using Groovy build.gradle
build scripts it should work transparently but Kotlin build.gradle.kts
build scripts will require
you to use the Property.set API:
1apollo {
2 // Replace:
3 setGenerateKotlinModels(true)
4
5 // With:
6 generateKotlinModels.set(true) // highlight-line
7}
Also, the classes of the plugin have been split into an api
part and an internal
one. If you were relying on fully qualified class names from your build.gradle.kts
files, you will have to tweak them:
1// Replace:
2import com.apollographql.apollo.gradle.ApolloExtension
3
4// With:
5import com.apollographql.apollo.gradle.api.ApolloExtension // highlight-line
Breaking changes in generated Kotlin models with inline fragments:
Field inlineFragment
is no longer generated with a new Apollo 1.3.0 release for Kotlin models.
For example:
previous version of model with inline fragments
1data class Hero(
2 val __typename: String,
3 /**
4 * The name of the character
5 */
6 val name: String,
7 val inlineFragment: HeroCharacter?
8 ) {
9 val asHuman: AsHuman? = inlineFragment as? AsHuman
10
11 val asDroid: AsDroid? = inlineFragment as? AsDroid
12...
new version of generated model with inline fragments
1 data class Hero(
2 val __typename: String,
3 /**
4 * The name of the character
5 */
6 val name: String,
7 val asHuman: AsHuman?,
8 val asDroid: AsDroid?
9 )
Motivation: there is an issue with previous version of generated model, there are cases when specified multiple inline fragments
should be resolved for the same GraphQL type. For example imagine that GraphQL schema defines this hierarchy of types
Character <- Hero <- Human
. Having this GraphQL query:
1query {
2 character {
3 name
4 ... on Hero { ... }
5 ... on Human { ... }
6 }
7}
both inline fragments on Hero
and on Human
should be resolved for character type Human
as Hero
is super type of Human
.
Previous version of generated model for Character
didn't resolve both inline fragments but rather first declared ... on Hero
. New
version resolves both fragments on Hero
and on Human
.
Migration:
If you have this code to get access to the resolved inline fragment:
1when (hero.inlineFragment) {
2 is Hero.AsHuman -> // ...
3 is Hero.AsDroid -> // ...
4}
you should change it to check all declared inline fragments for nullability, as it's possible now to have multiple resolved fragments:
1if (hero.asHuman != null) {
2 // ...
3}
4
5if (hero.asDroid != null) {
6 // ...
7}
Singularization
Singularization rules have been improved (see 1888 ). That means the name of some classes that were previously wrongly or badly singularized might have changed. Check for a generated class with a similar name if that happens.
Nested class names
Nested classes are now allowed to have the same name as their parent (see 1893 ). If you were previously using such a class, the numbered suffix will be removed.
Transformed queries removal
Version 1.3.0 can now optionally generate a operationOutput.json
file. This file will contain the generated queries source, operation name
and operation ID. You can use them to whitelist the operation on your server or any other use case. See
1841 for details.
Since operationOutput.json is a superset of the transformed queries, transformed queries have been removed. If you were using transformed queries, you will now have to use operationOutput.json.
Espresso Idling Resources
Idling Resources integration is moved to AndroidX! This is a potential breaking change for users who has not migrated to AndroidX yet. If you haven't you can still use the 1.2.x version in your test code.
The artifact is also renamed to make its intention more obvious. Documentation for idling resource can be found here
1 // Replace:
2 androidTestImplementation("com.apollographql.apollo:apollo-espresso-support:x.y.z")
3
4 // With:
5 androidTestImplementation("com.apollographql.apollo:apollo-idling-resource:x.y.z") // highlight-line