v3.0.0-beta02

This version introduces fluent APIs on operations, more multiplatform targets, more compatibility helpers
to ease transition from v2.x, and other fixes.

✨ [new and breaking] Fluent APIs (#3447)

The API to execute operations now uses the Fluent style, where you can chain method calls together. The ApolloClient query, mutate and subscribe methods now return an ApolloCall that can be configured, and on which you can call execute to execute the operation.

Before:

val request = ApolloRequest.Builder(HeroQuery()).fetchPolicy(FetchPolicy.NetworkOnly).build()
val response = apolloClient.query(request)

After (fluent):

val response = apolloClient.query(HeroQuery())
        .fetchPolicy(FetchPolicy.NetworkOnly)
        .execute()

If you were using cacheAndNetwork, it's now executeCacheAndNetwork:

// Before
apolloClient.cacheAndNetwork(query)

// After
apolloClient.query(query).executeCacheAndNetwork()

✨ [new] New multiplatform targets (#3487)

This release adds support for these new targets:

• macosArm64
• iosArm64
• iosSimulatorArm64
• watchosArm64
• watchosSimulatorArm64
• tvosArm64
• tvosX64
• tvosSimulatorArm64

Additionally, apollo-api (models) is now compiled for linuxX64. Follow this issue for updates on this - and contributions on this area are welcome!

✨ [new] Sealed interfaces in generated code (#3448)

When using the responseBased codegen, now interfaces will be generated as sealed when possible.

Because sealed interfaces are only available since Kotlin 1.5, a new Gradle option languageVersion has been introduced to control this behavior (and potentially future language features used by the codegen).

✨ [new] Version 2 compatibility helpers

To ease transition from 2.x, this release provides:

• a CustomTypeAdapter that can be used for custom scalars in the same way as in 2.x
• an Input helper that will map to 3.x Optional automatically

These helpers are deprecated and are to be used only as a temporary measure - they will be removed in a future version.

💙 External contributors

Thanks to @davidec-twinlogix, @pauldavies83 @nachtien and @Pitel for their awesome contributions!

👷 All Changes

• Add a "compat" v2 CustomTypeAdapter to v3 Adapter API (#3482)
• Add a few targets (#3487)
• Add parsing of non-standard Error fields (#3485)
• Resolve name clashes the same way as in 2.x (#3486)
• Make the packageName error more explicit for users that are migrating (#3477)
• Fix pointer use after free (#3478)
• Add Apple Silicon iOS Simulator Targets (#3481)
• Check minimum Kotlin version in the plugin (#3475)
• Migrate HttpRequest With-ers to Builders (#3474)
• Add .customScalarAdapter(CustomScalarAdapters) on ApolloClient.Builder (#3472)
• Bump KSP and Okio to stable 🎉 (#3473)
• [RFC] Fluent query API (#3447)
• Generate sealed interfaces in response based codegen (#3448)
• Add MySealedClass.knownValues() (#3465)
• Added Long support to RecordFieldJsonAdapter (#3468)
• Add an iOSX64 test and publish apollo-testing-support for ios (#3463)
• Add customTypesMapping for backward compatibility (#3452)
• Add Input backward compat layer (#3456)
• Rename include to includes (#3451)

v3.0.0-beta01

Version 3.0.0-beta01 is the first Beta release for Apollo Android 3 🎉. While there are no API stability guarantees just yet, 3.0.0-beta01 introduces binary compatibility validation to monitor the breaking changes and they should happen less frequently from now on.

One important API change in 3.0.0-beta01 is the change from with-ers to Builders. It also has a useVersion2Compat Gradle property to ease the transition from 2.x.

In addition, 3.0.0-beta01 introduces JavaScript runtime and cache support and new Test Builders APIs to generate fake data models.

💜 Many thanks to @Pitel and @dchappelle for the awesome additions to this release !💜

✨[new] JavaScript runtime and cache support (#3208)

Version 3.0.0-beta01 has support for JavaScript targets courtesy of @Pitel. It contains both IR and LEGACY artifacts. To use it in your builds, add apollo-runtime and apollo-normalized-cache dependencies to your build.gradle[.kts]:

kotlin {
  js(IR) { // or js(LEGACY)
    sourceSets {
      val commonMain by getting {
        // To use HTTP and runtime 
        implementation("com.apollographql.apollo3:apollo-runtime:3.0.0-beta01")
        // To use in-memory cache
        implementation("com.apollographql.apollo3:apollo-normalized-cache:3.0.0-beta01")
      }
    }
  }
}

This is everything needed. All the APIs work the same as their equivalent JVM/native ones.

Two caveats:

• SQLite is not supported yet (see #3442)
• WebSocket are not supported yet (see #3443)

Contributions are very welcome, feel free to reach out on the kotlin lang slack to get started!

✨[new] Test Builders API (#3415)

You can now opt-in generation of Test Builders that make it easier to build fake models for your operations. Test Builders allow to generate fake data using a type safe DSL and provides mock values for fields so that you don't have to specify them all.

To enable Test Builders, add the below to your Gradle scripts:

apollo {
  generateTestBuilders.set(true)
}

This will generate builders and add them to your test sourceSets. You can use them to generate fake data:

// Import the generated TestBuilder
import com.example.test.SimpleQuery_TestBuilder.Data

@Test
fun test() {
  // Data is an extension function that will build a SimpleQuery.Data model
  val data = SimpleQuery.Data {
    // Specify values for fields that you want to control
    hero = droidHero {
      name = "R2D2"
      friends = listOf(
          friend {
            name = "Luke"
          }
      )
      // leave other fields untouched, and they will be returned with mocked data
      // planet = ...
    }
  }
  
  // Use the returned data
}

You can control the returned mock data using the TestResolver API:

val myTestResolver = object: DefaultTestResolver() {
  fun resolveInt(path: List<Any>): Int {
    // Always return 42 in fake data for Int fields
    return 42
  }
}

val data = SimpleQuery.Data(myTestResolver) {}
// Yay, now every Int field in `data` is 42!

✨🚧✨ [new and breaking] Version2 compatibility

3.0.0-beta01 introduces new Gradle options for better compatibility with versions 2. Most of the changes in this section can be reverted through configuration options but some had breaking side effects like valueOf being renamed to safeValueOf for enums.

sealedClassesForEnumsMatching allows generating Kotlin enums for GraphQL enums.

Apollo 3.x generates sealed classes for Kotlin enums. As paradoxical as it may seem, sealed classes a better representation of GraphQL enums because they allow to expose the rawValue of new enums that are not know at compile time. Sealed classes can also handle when exhaustivity just like Kotlin enums and are generally more flexible. Using them may change the calling code though so as a temporary migration helper, you can now fallback to enum like in 2.x by setting sealedClassesForEnumsMatching to an empty list instead of the default listOf(".*"):

apollo {
  sealedClassesForEnumsMatching.set(emptyList())
}

One side effect of this change is that the generated MySealedClass.valueOf() has been renamed to MySealedClass.safeValueOf().

generateOptionalOperationVariables allows wrapping your variables in Optional<>.

By default Apollo Android 3 skips the Optional<> wrapper for nullable variables. This simplifies the call site in the vast majority of cases where the variable is actually sent alongside the query.

There might be some rare occasions where you want to be able to omit a variable. For these cases, you can add an @optional directive:

# a query that allows omitting before and/or after for bi-directional pagination
query MyQuery($before: String @optional, $after: String @optional) {
  items {
    title
  }
}

If you have a lot of those queries, or if you prefer the 2.x behaviour, you can now opt-out globally:

apollo {
  generateOptionalOperationVariables.set(true)
}

codegenModels defaults to "operationBased"

3.0.0-beta01 now defaults to "operationBased" models. "operationBased" models match your GraphQL operations 1:1 and skip the extra .fragment synthetic fields that are present in "compat" models. Because they are simpler to understand, generate and execute, they are now the default. You can revert to "compat" codegen with the codegenModels Gradle option:

apollo {
  codegenModels.set(MODELS_COMPAT)
}

useVersion2Compat()

For all these options, you can now fallback to the 2.x behaviour with useVersion2Compat(). This is a shorthand function that configures the above options to match the 2.x behaviour. useVersion2Compat is a helper to facilitate the migration and will be removed in a future update.

🚧[breaking] ApolloClient and ApolloRequest Builder APIs

Following the with-er vs Builder vs DSL RFC, we decided to move the main APIs to Builders. Builders are widely accepted, battle proven APIs that play nicely with Java and will make it easier to maintain Apollo Android in the long run.

While this beta-01 release keeps the with-ers, they will be removed before Apollo Android 3 goes stable so now is a good time to update.

To build an ApolloClient:

// Replace
val apolloClient = ApolloClient("https://com.example/graphql")
    .withNormalizedCache(normalizedCacheFactory)

// With
val apolloClient = ApolloClient.Builder()
    .serverUrl("https://com.example/graphql")
    .normalizedCache(normalizedCacheFactory)
    .build()

To build a ApolloRequest:

// Replace
val apolloRequest = ApolloRequest(query)
    .withFetchPolicy(FetchPolicy.CacheFirst)

// With
val apolloRequest = ApolloRequest.Builder(query)
    .fetchPolicy(FetchPolicy.CacheFirst)
    .build()

Websocket updates

The WebSocket code has been revamped to support client-initiated ping-pong for graphql-ws as well as a better separation between common code and protocol specific code.

A side effect is that WebSocket protocols are now configured using a WsProtocol.Factory:

// Replace
val apolloClient = ApolloClient(
    networkTransport = WebSocketNetworkTransport(
        serverUrl = "http://localhost:9090/graphql",
        protocol = GraphQLWsProtocol()
    )
)

// With
val apolloClient = ApolloClient.Builder()
    .networkTransport(
        WebSocketNetworkTransport(
            serverUrl = "http://localhost:9090/graphql",
            protocolFactory = GraphQLWsProtocol.Factory()
        )
    )
    .build()

👷 All Changes

• Mutations over WebSocket (graphql-ws protocol) may hang indefinitely … by @dchappelle in #3383
• Fix nanosecond conversion on native by @martinbonnin in #3386
• Support Ping/Pong messages for graphql-transport-ws (#3291) by @dchappelle in #3401
• WebSockets: better separate common code and protocol-specific code by @martinbonnin in #3405
• Bump SqlDelight by @martinbonnin in #3407
• Bump Kotlin to 1.5.31 by @martinbonnin in #3414
• Allow isFromCache on all ApolloResponses by @martinbonnin in #3416
• Update ApolloClient and ApolloRequest APIs from With-ers to Builders by @BoD in #3404
• JavaScript by @Pitel in #3208
• Add Test Builders by @martinbonnin in https://github.com/apollographq...

v2.5.10

Version 2.5.10 is a maintenance release with a few bugfixes, mutiny support and a new Gradle register${VariantName}ApolloOperations task to register your operations to the Apollo registry.

💜 Many thanks to @ProVir, @aoudiamoncef and @jgarrow for their contributions !💜

✨[new] Mutiny support (#3213)

Version 2.5.10 adds support for the Mutiny reactive library.

Add the dependency:

// Mutiny support
implementation 'com.apollographql.apollo:apollo-mutiny-support:x.y.z'

And convert your ApolloCall to a Mutiny Uni:

// Create a query object
val query = EpisodeHeroNameQuery(episode = Episode.EMPIRE.toInput())

// Directly create Uni with Kotlin extension
val uni = apolloClient.mutinyQuery(query)

Read more in the documentation

✨[new] register${VariantName}ApolloOperations (#3403)

If you're using Apollo safelisting, you can now upload the transformed operations from Gradle directly. Add a registerOperations {} block to the apollo {} block:

apollo {
  service("service") {
    registerOperations {
      // You can get your key from https://studio.apollographql.com/graph/$graph/settings
      key.set(System.getenv("APOLLO_KEY"))
      graph.set(System.getenv("APOLLO_GRAPH"))
      // Use "current" by default or any other graph variant
      graphVariant.set("current")
    }
  }
}

Then call ./gradlew registerMainServiceApolloOperations to register your operations to the registry. The operations will be registered including the added __typename fields that might be added during codegen.

👷 All Changes

• refactor: RxJava2/3 support by @aoudiamoncef in #3166
• Remove duplicate ExecutionContext by @martinbonnin in #3213
• feat: add Mutiny support by @aoudiamoncef in #3198
• Updated coroutines for use native-mt version by @ProVir in #3330
• Increase Json nesting to 256 by @martinbonnin in #3334
• Give a hint at errorPayload by @martinbonnin in #3381
• Workaround wrong input field default values by @martinbonnin in #3398
• do not crash when trying to indent the GraphQL document by @martinbonnin in #3399
• Add ./gradlew push${MainService}ApolloOperations by @martinbonnin in #3403
• Operation Registry: normalize queries before computing the hash by @martinbonnin in #3406

New Contributors

• @ProVir made their first contribution in #3330
• @jgarrow made their first contribution in #3346
• @BoD made their first contribution in #3396

Full Changelog: v2.5.9...v2.5.10

v3.0.0-alpha07

Version 3.0.0-alpha07 has new builtin Adapters for java.time, better custom scalar handling for multi module projects and multiple fixes for MPP and json parsers.

💜 Many thanks to @ProVir, @ychescale9 and @pauldavies83 for all the feedback and investigations !💜

✨[new] Adapters for java.time

Like there were adapters for kotlinx.datetime, you can now use java.time adapters from the apollo-adapters package:

• com.apollographql.apollo3.adapter.JavaInstantAdapter
• com.apollographql.apollo3.adapter.JavaLocalDateAdapter
• com.apollographql.apollo3.adapter.JavaLocalDateTimeAdapter

🚧[breaking] renamed kotlinx.datetime Adapters

To keep things symmetrical with the java.timeadapters, the kotlinx.datetime adapters are now named:

• com.apollographql.apollo3.adapter.KotlinxInstantAdapter
• com.apollographql.apollo3.adapter.KotlinxLocalDateAdapter
• com.apollographql.apollo3.adapter.KotlinxLocalDateTimeAdapter

🚧[breaking] new LongAdapter package name

Because LongAdapter is widely used and doesn't require any additional dependencies, it is now in the builtin apollo-api package

// Replace
com.apollographql.apollo3.adapter.LongAdapter

// With
com.apollographql.apollo3.api.LongAdapter

👷 All Changes

• Fix OutOfBoundsException in MapJsonReader (#3375)
• Add Long support to JsonReader and JsonWriter (#3370)
• Fix structured concurrency issues dur to runCatching (#3364)
• add a convenience ApolloClient.apolloStore (#3367)
• simplify scalar handling (#3362)
• add java.time Adapters (#3360)
• relax freezing restrictions on the store (#3358)

v3.0.0-alpha06

Hotfix release to fix Android Studio autocomplete for generated files (#3354)

v3.0.0-alpha05

3.0.0-alpha05 is an incremental update on top of alpha04 with a few important fixes. Many thanks to all the feedback, in particular from @rickclephas, @ProVir, @ychescale9 and @james on the Kotlinlang slack. Thank you 💜!

Relaxed freezing restrictions (#3350)

The Kotlin Native runtime was too strict in ensuring the Continuations were never frozen, which caused exceptions when used with coroutines-native-mt. This check has been removed.

Add ApolloClient.clearNormalizedCache (#3349)

To ease the transition from 2.x, clearNormalizedCache has been added as a deprecated function and will be removed for 3.1

Introduce __Schema to hold the list of all types (#3348)

Because only used types are generated in alpha04, we lost the ability to compute possible types in a typesafe way. This PR re-introduces this with an opt-it generateSchema Gradle property:

apollo {
  generateSchema.set(true)
}

This will:

1. Force generate all composite types (interfaces, objects, unions)
2. generate a __Schema class that will hold a list of all composite types

The __Schema class has a possibleTypes() function that can lookup possible types from the list of types:

    assertEquals(
        setOf(Cat.type, Dog.type, Crocodile.type),
        __Schema.possibleTypes(Animal.type).toSet()
    )

Fix custom scalars in multi module projects (#3341)

For multi-project builds, custom scalar were registered twice, leading to a validation error. This is now fixed.

v3.0.0-alpha04

3.0.0-alpha04 brings Java codegen and ApolloIdlingResource in Apollo Android 3. These were the final pieces that were not ported to Apollo Android 3 yet 🎉..
In addition, it brings some consistency improvements in the codegen/Gradle setup as well bump the max json stack size to 256 and other ergonomic improvements and fixes.

As we move towards a stable version, we'll have to settle for the current with-er API or Builders. Let us know what you think by letting a comment on the RFC.

✨[new] Java Codegen

Apollo Android 3 now generates Java models if the Kotlin plugin is not applied in your project. This is detected automatically and should work in the vast majority of cases. If you want to force Java codegen while still using the Kotlin plugin, you can set generateKotlinModels.set(false) in your Gradle scripts:

apollo {
  // Generate Java classes regardless of whether the Kotlin plugin is applied
  generateKotlinModels.set(false)
}

Java models work like Kotlin models and use the same runtime. With the exception of default parameters, they are compatible with Kotlin operationBased models so you can change the target language without having to update most of your code.

✨[new] apollo-idling-resource

apollo-idling-resource is now available in Apollo Android 3. You can include it with the apollo-idling-resource artifact:

dependencies {
  testImplementation("com.apollographql.apollo3:apollo-idling-resource:$version")
}

And create an ApolloClient that will update the IdlingResource:

val idlingResource = ApolloIdlingResource("test")
val apolloClient = ApolloClient("https://...")
    .withIdlingResource(idlingResource)

✨[new] valueOf for enums

Many thanks to @kubode for the contribution 💜

For GraphQL enums generated as sealed class, you can now call valueOf to parse a String to a given enum value (or Unknown__ if unknown):

Given the below enum:

enum Direction {
  NORTH,
  EAST,
  SOUTH,
  WEST
}

You can use:

assertEquals(Direction.NORTH, Direction.valueOf("NORTH"))
assertEquals(Direction.Unknown__("NORTH-WEST"), Direction.valueOf("NORTH-WEST"))

✨[new] Platform errors for ApolloNetworkError

Many thanks to @ProVir for the help getting this done 💜

When something wrong happens during a network request, the runtime will throw a ApolloNetworkError exception. You can now access the underlying platform error with ApolloNetworkError.platformCause:

// On iOS you can cast to NSError
try {
  apolloClient.query(query)
} catch (e: ApolloNetworkError) {
  when ((e.platformCause as NSError?)?.domain) {
    NSURLErrorDomain -> // handle NSURLErrorDomain errors ...
  }
}

// On Android/JVM, platformCause is the same Throwable as Cause:
try {
  apolloClient.query(query)
} catch (e: ApolloNetworkError) {
  when (e.cause) {
    is UnknownHostException -> // handle UnknownHostException errors ...
  }
}

🚧[breaking] Mandatory package name

Because the default of an empty package name creates issues with kapt, it is now mandatory to set the package name of generated models:

apollo {
  // Use the same packageName for all generated models
  packageName.set("com.example")
  // Or use a package name derived from the file location
  packageNamesFromFilePaths()
}

🚧[breaking] Schema Types

For consistency, and in order to support multi-modules scenarios where some types are only generated in some modules, custom scalars, object and interface types are now generated as top-level classes in the .type package name, like input objects and enums instead of being wrapped in a Types object. Each schema type has a static type: CompiledType property so you can access the type name in a type safe way.

// Replace
Types.Launch.name

// With 
Launch.type.name

If you were using generated CustomScalarType instances to register your custom scalar adapters, these are moved to the top level as well:

// Replace
ApolloClient("https://").withCustomScalarAdapter(Types.GeoPoint, geoPointAdapter)

// With
ApolloClient("https://").withCustomScalarAdapter(GeoPoint.type, geoPointAdapter)

🚧[breaking] Removed DefaultHttpRequestComposerParams

Because DefaultHttpRequestComposerParams was setting multiple parameters at the same time (HTTP headers, method, etc..), setting one of them would overwrite a default set on the client. Instead of using DefaultHttpRequestComposerParams, set parameters individually:

apolloClient.withHttpHeader("name", "value")
apolloRequest.withHttpHeader("otherName", "otherValue")

👷 All Changes

• Input array coercion (#3337)
• Java Codegen (#3335)
• bump the max stack size to 256 (#3333)
• Adds valueOf to the enum types (#3328)
• Update to AGP 4.2 (#3324)
• bump Kotlin (#3319)
• Expose NSError (#3315)
• fix visibility of presentIfNotNull. (#3316)
• Add apollo-rx3-support (#3303)
• Move ApolloIdlingResource to apollo-idling-resource (#3302)
• simplify the Android setup (#3293)
• Make it possible to override ExecutionContext properties individually (#3294)
• Mandate package name (#3295)
• add more diagnostics for normalization failures (#3286)
• allow multiple HTTP headers with the same name (#3287)
• add error.path and error.extensions (#3285)
• Add 3.x ApolloIdlingResource (#3282)
• bump kotlin-compile-testing and enable warningsAsErrors again (#3278)
• add a way to disable Kdoc during development (#3279)
• Minor Cleanups (#3277)
• Simplify output dir connection (#3276)
• Remove split packages (#3275)
• Remove deprecated modules and move tests to the root level (#3274)
• Encode defaultValue as GraphQL value in introspection schemas (#3272)
• add a DefaultHttpNetworkTransport overload that takes a serverUrl (#3273)

v3.0.0-alpha03

3.0.0-alpha03 is a release with a bunch of bugfixes and documentation fixes.

The Kdoc for the current dev-3.x version is now available at: https://apollographql.github.io/apollo-android/kdoc/

👷‍ Bugfixes

• Publish Kdoc (#3250)
• Fix circular references when reading the cache (#3263)
• Websocket closed error missing from graphql-ws subscription (#3257)

❤️ External contributors

Many thanks to @dchapelle for the work on WebSockets and @PHPirates and @omaksymov for the documentation fixes!

v3.0.0-alpha02

This version reworks the CacheResolver API to hopefully clarify its usage as well as allow more advanced use cases if needed.

ObjectIdGenerator and CacheResolver APIs

This version splits the CacheResolver API in two distinct parts:

• ObjectIdGenerator.cacheKeyForObject
  • takes Json data as input and returns a unique id for an object.
  • is used after a network request
  • is used during normalization when writing to the cache
• CacheResolver.resolveField
  • takes a GraphQL field and operation variables as input and generates data for this field
  • this data can be a CacheKey for objects but it can also be any other data if needed. In that respect, it's closer to a resolver as might be found in apollo-server
  • is used before a network request
  • is used when reading the cache

Previously, both methods were in CacheResolver even if under the hood, the code path were very different. By separating them, it makes it explicit and also makes it possible to only implement one of them.

Note: In general, prefer using @typePolicy and @fieldPolicy that provide a declarative/easier way to manage normalization and resolution.

ObjectIdGenerator is usually the most common one. It gives objects a unique id:

type Product {
  uid: String!
  name: String!
  price: Float!
}

// An ObjectIdGenerator that uses the "uid" property if it exists
object UidObjectIdGenerator : ObjectIdGenerator {
  override fun cacheKeyForObject(obj: Map<String, Any?>, context: ObjectIdGeneratorContext): CacheKey? {
    val typename = obj["__typename"]?.toString()
    val uid = obj["uid"]?.toString()

    return if (typename != null && uid != null) {
      CacheKey.from(typename, listOf(uid))
    } else {
      null
    }
  }
}

CacheResolver allows resolving a specific field from a query:

query GetProduct($uid: String!) {
  product(uid: $uid) {
    uid
    name
    price
  }
}

object UidCacheResolver: CacheResolver {
  override fun resolveField(field: CompiledField, variables: Executable.Variables, parent: Map<String, Any?>, parentId: String): Any? {
    var type = field.type
    if (type is CompiledNotNullType) {
      type = type.ofType
    }
    if (type !is ObjectType) {
      // This only works for concrete types
      return MapCacheResolver.resolveField(field, variables, parent, parentId)
    }

    val uid = field.resolveArgument("uid", variables)?.toString()
    if (uid != null) {
       return CacheKey.from(type.name, listOf(uid))
    }

    // Always fallback to the default resolver
    return MapCacheResolver.resolveField(field, variables, parent, parentId)
  }
}

Bug fixes

• Be robust to SDL schemas that already contain builtin definitions (#3241)

v3.0.0-alpha01

This version is the first alpha on the road to a 3.0.0 release!

Apollo Android 3 rewrites a lot of the internals to be Kotlin first and support a multiplatform cache. It also has performance improvements, new codegen options, support for multiple client directives and much more!

This document lists the most important changes. For more details, consult the preliminary docs and the migration guide.

This is a big release and the code is typically less mature than in the main branch. Please report any issue, we'll fix them urgently. You can also reach out in kotlinlang's #apollo-android slack channel for more general discussions.

Kotlin first

This version is 100% written in Kotlin, generates Kotlin models by default and exposes Kotlin first APIs.

Using Kotlin default parameters, Builders are removed:

import com.apollographql.apollo3.ApolloClient

val apolloClient = ApolloClient("https://com.example/graphql")

Queries are suspend fun, Subscriptions are Flow<Response<D>>:

val response = apolloClient.query(MyQuery())
// do something with response

apolloClient.subscribe(MySubscription()).collect { response ->
    // react to changes in your backend
}

Java codegen is not working but will be added in a future update. For details and updates, see this GitHub issue

Multiplatform

This version unifies apollo-runtime and apollo-runtime-kotlin. You can now use apollo-runtime for both the JVM and iOS/MacOS:

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("com.apollographql.apollo3:apollo-runtime:3.0.0-alpha01")
            }
        }
    }
}

The normalized cache is multiplatform too and both apollo-normalized-cache (for memory cache) and apollo-normalized-cache-sqlite (for persistent cache) can be added to the commonMain sourceSet.

The In-Memory cache uses a custom LruCache that supports maxSize and weighter options. The SQLite cache uses SQLDelight to support both JVM and native targets.

val apolloClient = ApolloClient("https://com.example/graphql")
                        .withNormalizedCache(MemoryCacheFactory(maxSize = 1024 * 1024))

val apolloRequest = ApolloRequest(GetHeroQuery()).withFetchPolicy(FetchPolicy.CacheFirst)
val apolloResponse = apolloClient.query(apolloRequest)

Current feature matrix:

	JVM	iOS/MacOS	JS
apollo-api (models)	✅	✅	✅
apollo-runtime (network, query batching, apq, ...)	✅	✅	🚫
apollo-normalized-cache	✅	✅	🚫
apollo-normalized-cache-sqlite	✅	✅	🚫
apollo-http-cache	✅	🚫	🚫

Performance improvements

SQLite batching

SQLite batching batches SQL requests instead of executing them sequentially. This can speed up reading a complex query by a factor 2x+ (benchmarks). This is especially true for queries that contain lists:

{
  "data": {
    "launches": {
      "launches": [
        {
          "id": "0",
          "site": "CCAFS SLC 40"
        },
        ...
        {
          "id": "99",
          "site": "CCBGS 80"
        }
      ]
    }
  }
}

Reading the above data from the cache would take 103 SQL queries with Apollo Android 2 (1 for the root, 1 for data, 1 for launches, 1 for each launch). Apollo Android 3 uses 4 SQL queries, executing all the launches at the same time.

Streaming parser

When it's possible, the parsers create the models as they read bytes from the network. By amortizing parsing during IO, the latency is smaller leading to faster UIs. It's not always possible though. At the moment, the parsers fall back to buffering when fragments are encountered because fragments may contain merged fields that need to rewind in the json stream:

{
    hero {
        friend {
            name
        }
        ... on Droid {
            # friend is a merged field which Apollo Android needs to read twice
            friend {
                id
            }
        }
    }
}

A future version might be more granular and only fallback to buffering when merged fields are actually used.

Codegen options

The codegen has been rethought with the goal of supporting Fragments as Interfaces.

To say it turned out to be a complex feature would be a understatement. GraphQL is a very rich language and supporting all the edge cases that come with polymorphism, @include/@skip directives and more would not only be very difficult to implement but also generate very complex code (see 3144). While fragments as interfaces are not enabled by default, the new codegen allows to experiment with different options and features.

codegenModels

The codegen supports 3 modes:

• compat (default) uses the same structure as 2.x.
• operationBased generates simpler models that map the GraphQL operation 1:1.
• responseBased generates more complex models that map the Sson response 1:1.

responseBased models will generate fragments as interfaces and can always use streaming parsers. They do not support @include/@skip directives on fragments and will generate sensibly more complex code.

Read Codegen.md for more details about the different codegen modes.

To change the codegen mode, add this to your build.gradle[.kts]:

apollo {
    codegenModels.set("responseBased") // or "operationBased", or "compat"
}

Types.kt

The codegen now generates a list of the different types in the schema.

You can use these to get the different __typename in a type-safe way:

val typename = Types.Human.name 
// "Human"

or find the possible types of a given interface:

val possibleTypes = Types.possibleTypes(Types.Character)
// listOf(Types.Human, Types.Droid)

apollo-graphql-ast

This version includes apollo-graphql-ast that can parse GraphQL documents into an AST. Use it to analyze/modify GraphQL files:

file.parseAsGQLDocument()
    .definitions
    .filterIsInstance<GQLOperationDefinition>
    .forEach {
        println("File $file.name contains operation '$it.name'")
    }

Client directives

@nonnull

@nonnull turns nullable GraphQL fields into non-null Kotlin properties. Use them if such a field being null is generally the result of a larger error that you want to catch in a central place (more in docs):

query GetHero {
  # data.hero will be non-null
  hero @nonnull {
    name
  }
}

@optional

Apollo Android distinguishes between:

• nullable: whether a value is null or not
• optional: whether a value is present or not

The GraphQL spec makes non-nullable variables optional. A query like this:

query GetHero($id: String) {
    hero(id: $id) {
        name
    }
}

will be generated with an optional id constructor parameter:

class GetHeroQuery(val id: Optional<String?> = Optional.Absent)

While this is correct, this is also cumbersome. If you added the id variable in the first place, there is a very high chance you want to use it. Apollo Android 3 makes variables non-optional by default (but possibly nullable):

class GetHeroQuery(val id: String?)

If for some reason, you need to be able to omit the variable, you can opt-in optional again:

# id will be an optional constructor parameter
query GetHero($id: String @optional) {
    hero(id: $id) {
        name
    }
}

@typePolicy

You can use @typePolicy to tell the runtime how to compute a cache key from object fields:

extend type Book @typePolicy(keyFields: "isbn")

The above will add isbn wherever a Book is queried and use "Book:$isbn" as a cache key.

Since this works at the schema level, you can either modify your source schema or add an extra extra.graphqls file next to it that will be parsed at the same time.

@fieldPolicy

Symmetrically from @typePolicy, you can use @fieldPolicy to tell the runtime how to compute a cache key from a field and query variables.

Given this schema:

type Query {
    book(isbn: String!): Book
}

you can tell the runtime to use the isbn argument as a cache key with:

extend type Query @fieldPolicy(forField: "book", keyArgs: "isbn")

Apollo Adapters

This version includes an apollo-adapters artifact that includes Adapters for common custom scalar types:

• InstantAdapter for kotlinx.datetime.Instant ISO8601 dates
• LocalDateAdapter for kotlinx.datetime.LocalDate ISO8601 dates
• DateAdapter for java.util.Date ISO8601 dates
• LongAdapter for java.lang.Long
• BigDecimalAdapte...