:robot: A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform.
☑️ Apollo Clients User Survey |
---|
What do you like best about Apollo Kotlin? What needs to be improved? Please tell us by taking a one-minute survey. Your responses will help us understand Apollo Kotlin usage and allow us to serve you better. |
Apollo Kotlin (formerly known as Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL queries.
Apollo Kotlin executes queries and mutations against a GraphQL server and returns results as query-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around Map
s 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 UI uses.
Because generated types are query-specific, you can only access data that you actually specify as part of a query. If you don't ask for a particular field 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.
Apollo Kotlin is a Kotlin Multiplatform project.
Here's the current matrix of supported features per platform:
jvm |
Apple¹ |
js |
linuxX64 |
|
---|---|---|---|---|
apollo-api (models) |
✅ | ✅ | ✅ | ✅ |
apollo-runtime (network, query batching, apq, ...) |
✅ | ✅ | ✅ | 🚫 |
apollo-normalized-cache |
✅ | ✅ | ✅ | 🚫 |
apollo-adapters |
✅ | ✅ | ✅ | 🚫 |
apollo-normalized-cache-sqlite |
✅ | ✅ | 🚫 | 🚫 |
apollo-http-cache |
✅ | 🚫 | 🚫 | 🚫 |
¹: Apple currently includes:
macosX64
macosArm64
iosArm64
iosX64
iosSimulatorArm64
watchosArm32
watchosArm64
watchosSimulatorArm64
tvosArm64
tvosX64
tvosSimulatorArm64
Check the project website for in depth documentation.
If you are new to GraphQL, check out the tutorial that will guide you through building an Android app using Apollo, Kotlin and coroutines.
If you'd like to add Apollo Kotlin 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.6"
}
Add the runtime dependency:
dependencies {
implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.6")
}
Set the package name to use for the generated models:
apollo {
service("service") {
packageName.set("com.example")
}
}
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:
cp ${schema} ${module}/src/main/graphql/
Write a query in a ${module}/src/main/graphql/GetRepository.graphql
file:
query HeroQuery($id: String!) {
hero(id: $id) {
id
name
appearsIn
}
}
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()
.serverUrl("https://example.com/graphql")
.build()
// Execute your query. This will suspend until the response is received.
val response = apolloClient.query(HeroQuery(id = "1")).execute()
println("Hero.name=${response.data?.hero?.name}")
To learn more about other Apollo Kotlin APIs:
Some platforms have specific runtime requirements:
apollo-http-cache
and apollo-adapters
require enabling core library desugaring on Android API levels < 26)At build time, it requires:
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.
An experimental 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.
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.6"
}
repositories {
mavenCentral()
}
dependencies {
implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.6")
// optional: if you want to use the normalized cache
implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.6")
// 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
implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.6")
}
Latest development changes are available in Sonatype's snapshots repository:
// build.gradle.kts
repositories {
maven {
url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
}
mavenCentral()
// other repositories...
}
// settings.gradle.kts
pluginManagement {
repositories {
maven {
url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
}
gradlePluginPortal()
mavenCentral()
// other repositories...
}
}
And then use the 4.0.0-beta.7-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.
Apollo Kotlin is very modular and publishes several artifacts.
-incubating
are not finalized yet and subject to change any time.@ApolloExperimental
that are subject to change at any time.If you'd like to contribute, please see Contributing.md.
ApolloClient
(doc)Apollo builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:
Check out the Odyssey learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the Apollo Community to interact with and get technical help from the GraphQL community.