Launch GraphOS Studio
You're viewing documentation for an upcoming version of this software. Switch to the latest stable version.

Introduction to Apollo Kotlin

A strongly-typed, caching GraphQL client for Java and Kotlin multiplatform

πŸ“£ Apollo Kotlin 3 is generally available. If you're using Apollo Android 2.x, see the migration guide. You can also view the 2.x docs.

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

executes queries and against a and returns results as -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 definitions your UI uses.

Because generated types are -specific, you can only access data that you actually specify as part of a query. If you don't ask for a particular in a query, 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 Java/Kotlin app, including multiplatform.


  • Java and Kotlin Multiplatform code generation
  • Queries, and s
  • Reflection-free parsing
  • Normalized cache
  • Custom types
  • HTTP cache
  • Auto
  • batching
  • File uploads
  • Espresso IdlingResource
  • Fake models for tests
  • AppSync and -ws websockets
  • AST parser


is a Kotlin Multiplatform project.

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

apollo-api (models)βœ…βœ…βœ…βœ…
apollo-runtime (network, query batching, apq, ...)βœ…βœ…βœ…πŸš«

ΒΉ: Apple currently includes:

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

Getting started

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

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

Add the plugin to your build.gradle.kts:

plugins {
id("com.apollographql.apollo3") version "4.0.0-beta.4"

Add the runtime dependency:

dependencies {

Set the package name to use for the generated models:

apollo {
service("service") {

supports three types of files:

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

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

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

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

query HeroQuery($id: String!) {
hero(id: $id) {

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

// Create a client
val apolloClient = ApolloClient.Builder()
// Execute your query. This will suspend until the response is received.
val response = apolloClient.query(HeroQuery(id = "1")).execute()

To learn more about other Apollo Kotlin APIs:


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.8+ for JVM projects
  • Kotlin 1.9+ for native projects

Proguard / R8 configuration

As the code generated by 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

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

Installation instructions and more information can be found here.


The latest version is Maven Central

Check the changelog for the release history.

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

plugins {
id("com.apollographql.apollo3") version "4.0.0-beta.4"
repositories {
dependencies {
// optional: if you want to use the normalized cache
// optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
// and use apollo-api instead


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

// build.gradle.kts
repositories {
maven {
url = uri("")
// other repositories...
// settings.gradle.kts
pluginManagement {
repositories {
maven {
url = uri("")
// other repositories...

And then use the 4.0.0-beta.5-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

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.


If you'd like to contribute, please see

Community integrations

Additional resources

Migrating to v4
Edit on GitHubEditForumsDiscord

Β© 2024 Apollo Graph Inc.

Privacy Policy