Migrating to 1.3

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.apollo3 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.apollo3")

1// Replace:
2apply plugin: 'com.apollographql.android'
3
4// With:
5apply plugin: 'com.apollographql.apollo3'

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    packageName.set("com.github")
5  }
6  service("starwars") {
7    sourceFolder.set("com/starwars")
8    packageName.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:
7apollo {
8  service("service") {
9    srcDir("/path/to/your/graphql/queries/dir")
10  }
11}

1// Replace
2apollo {
3  service("service") {
4    sourceSet {
5      schemaFilePath = "/path/to/your/schema.json"
6      exclude = "**/*.gql"
7    }
8    outputPackageName = "com.example"
9  }
10}
11
12// With:
13apollo {
14  service("service") {
15    schemaFile.set(file("/path/to/your/schema.json"))
16    graphqlSourceDirectorySet.exclude("**/*.gql")
17    packageName.set("com.example")
18  }
19}

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  service("service") {
3    // Replace:
4    setGenerateKotlinModels(true)
5
6    // With:
7    generateKotlinModels.set(true)
8  }
9}

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.apollo3.gradle.ApolloExtension
3
4// With:
5import com.apollographql.apollo3.gradle.api.ApolloExtension

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.apollo3:apollo-espresso-support:x.y.z")
3
4  // With:
5  androidTestImplementation("com.apollographql.apollo3:deprecated-apollo-idling-resource:x.y.z")