Introduction to Apollo Kotlin

Apollo Kotlin (formerly Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL operations.

Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around Maps and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.

Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.

This library is designed primarily with Android in mind, but you can use it in any Kotlin (including multiplatform) and Java app.

Features

• Kotlin Multiplatform and Java code generation
• Queries, Mutations and Subscriptions
• Reflection-free parsing
• Normalized cache
• Custom scalar types
• HTTP cache
• Auto Persisted Queries
• Query batching
• File uploads
• Fake models for tests
• AppSync and graphql-ws websockets
• GraphQL AST parser
• Plugin for Android Studio and IntelliJ

Multiplatform

Apollo Kotlin is a Kotlin Multiplatform project.

Here's the current matrix of supported features per platform:

¹: Apple currently includes:

• macosX64
• macosArm64
• iosArm64
• iosX64
• iosSimulatorArm64
• watchosArm32
• watchosArm64
• watchosSimulatorArm64
• tvosArm64
• tvosX64
• tvosSimulatorArm64

Getting started

If you are new to GraphQL, check out the tutorial that will guide you through building an Android app using Apollo.

If you'd like to add Apollo Kotlin to an existing project, follow these steps:

Add the plugin to your build.gradle.kts:

1
plugins {
2
  id("com.apollographql.apollo3") version "4.0.0-beta.7"
3
}

Add the runtime dependency:

1
dependencies {
2
  implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
3
}

Set the package name to use for the generated models:

1
apollo {
2
  service("service") {
3
    packageName.set("com.example")
4
  }
5
}

Apollo Kotlin supports three types of files:

• .graphqls schema files: describes the types in your backend using the GraphQL syntax.
• .json schema files: describes the types in your backend using the Json syntax.
• .graphql executable files: describes your queries and operations in the GraphQL syntax.

By default, Apollo Kotlin requires a schema in your module's src/main/graphql directory. You can download a schema using introspection with the ./gradlew downloadApolloSchema task. Sometimes introspection is disabled and you will have to ask your backend team to provide a schema. Copy this schema to your module:

1
cp ${schema} ${module}/src/main/graphql/

Write a query in a ${module}/src/main/graphql/HeroQuery.graphql file:

1
query HeroQuery($id: String!) {
2
  hero(id: $id) {
3
    id
4
    name
5
    appearsIn
6
  }
7
}

Build your project. This will generate a HeroQuery class that you can use with an instance of ApolloClient:

1
// Create a client
2
  val apolloClient = ApolloClient.Builder()
3
      .serverUrl("https://example.com/graphql")
4
      .build()
5

6
  // Execute your query. This will suspend until the response is received.
7
  val response = apolloClient.query(HeroQuery(id = "1")).execute()
8

9
  println("Hero.name=${response.data?.hero?.name}")

To learn more about other Apollo Kotlin APIs:

• Execute your first mutation
• Handle custom scalar types
• Factor common patterns using fragments

Requirements

Some platforms have specific runtime requirements:

• JVM 8+
• Android API level 21+ (apollo-http-cache and apollo-adapters require enabling core library desugaring on Android API levels < 26)
• iOS 13+

At build time, it requires:

• Gradle 8.0+
• Kotlin 1.9+ for JVM projects
• Kotlin 2.0+ for native, JS, and Wasm projects

Proguard / R8 configuration

As the code generated by Apollo Kotlin doesn't use any reflection, it can safely be optimized / obfuscated by Proguard or R8, so no particular exclusions need to be configured.

Android Studio / IntelliJ plugin

A plugin for Android Studio and IntelliJ is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the GraphQL IntelliJ Plugin, navigation to GraphQL definitions, migration helpers, and more.

Installation instructions and more information can be found here.

Releases

The latest version is

Check the changelog for the release history.

Releases are hosted on Maven Central. The plugin is additionally hosted on the Gradle Plugin Portal

1
plugins {
2
  id("com.apollographql.apollo3") version "4.0.0-beta.7"
3
}
4

5
repositories {
6
  mavenCentral()
7
}
8

9
dependencies {
10
  implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
11

12
  // Optional: if you want to use the normalized cache
13
  implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.7")
14
  // Optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
15
  // and use apollo-api instead
16
  implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.7")
17
}

Snapshots

Latest development changes are available in Sonatype's snapshots repository:

1
// build.gradle.kts
2
repositories {
3
  maven {
4
    url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
5
  }
6
  mavenCentral()
7
  // other repositories...
8
}
9

10
// settings.gradle.kts
11
pluginManagement {
12
  repositories {
13
    maven {
14
      url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
15
    }
16
    gradlePluginPortal()
17
    mavenCentral()
18
    // other repositories...
19
  }
20
}

And then use the 4.0.0-beta.8-SNAPSHOT version for the plugin and libraries.

These snapshots are updated on each push to main.

Weekly snapshots for the Android Studio / IntelliJ plugin are also available.

Stability of different artifacts

Apollo Kotlin is very modular and publishes several artifacts.

• Artifacts ending with -incubating are not finalized yet and subject to change any time.
• Other artifacts observe Semantic Versioning.
  • No breaking change should be introduced in minor or patch releases except for symbols annotated with @ApolloExperimental that are subject to change at any time.
  • Deprecated symbols may be removed in the next major release. We strongly recommend removing deprecated usages before migrating to the next major version.

Contributing

If you'd like to contribute, please see Contributing.md.

Community integrations

• If you're using the Maven build tool, apollo-client-maven-plugin is a Maven plugin that calls the Apollo Kotlin compiler to generate your Java/Kotlin sources.
• If you're using Absinthe Phoenix subscriptions, kotlin-phoenix has a PhoenixNetworkTransport that you can use together with ApolloClient (doc)

Additional resources

• Confetti: A Kotlin Multiplatform conference app using Apollo Kotlin, SwiftUI and Jetpack Compose.
• MortyComposeKMM: A Kotlin Multiplatform Github template using Apollo Kotlin, SwiftUI and Jetpack Compose.
• A journey to Kotlin multiplatform: how the project was moved to Kotlin multiplatform, talk given at Kotliners in June 2020.
• #125, Fragmented Podcast: Why's and How's about Apollo Kotlin and the entire journey.
• GraphQL.org for an introduction and reference to GraphQL itself.
• apollographql.com to learn about Apollo open-source and commercial tools.
• The Apollo blog for long-form articles about GraphQL, feature announcements for Apollo, and guest articles from the community.
• The Apollo Twitter account for in-the-moment news.