Get started with Multiplatform (Experimental)
Note: Multiplatform support is experimental and still under heavy development, expect the API to change. If you have feedback, we'd love to hear it. Please see Contributing.md for how to get in touch.
You can also check out the multiplatform samples for more details.
Kotlin multiplatform allows to use the same queries and generated models on both Android and iOS. On Android it uses OkHttp to handle the HTTP calls. On iOS, it uses NSUrlSession.
Add the Gradle plugin
Get the latest version of Apollo Android from the Releases page.
In your app Gradle file, apply the com.apollographql.apollo3
plugin.
Using the plugins DSL:
plugins {
// ...
id("com.apollographql.apollo3").version("x.y.z")
}
Or using the legacy syntax:
buildscript {
// ...
classpath("com.apollographql.apollo3:apollo-gradle-plugin:x.y.z")
}
apply(plugin = "com.apollographql.apollo3")
The plugin is hosted both on the Gradle plugin portal and Maven Central.
By default the plugin generates models in the root package name. You can configure this in the apollo {}
block:
apollo {
packageName.set("com.example")
}
Add the runtime dependencies
Multiplatform uses a different artifact from apollo-runtime
. Its goal is to offer a coroutine-first API and is named apollo-runtime-kotlin
:
kotlin {
// targets
jvm()
iosArm64("ios")
sourceSets {
commonMain {
dependencies {
//
implementation("com.apollographql.apollo:apollo-runtime-kotlin:x.y.z")
}
}
}
}
Multithreaded coroutines
If using the x.y.z-native-mt branch of coroutines, gradle will replace the -native-mt version with the non-mt version as outlined here. To prevent this happening use the following:
implementation ("org.jetbrains.kotlinx:kotlinx-coroutines-core"){
version {
strictly("x.y.z-native-mt")
}
}
Download your schema.json
file
Apollo Android requires your GraphQL server's schema as either an introspection or SDL schema. Usually, it's a schema.[graphqls|json|sdl]
file. This page shows how to obtain a schema from your server using introspection.
Note: If you don't have a GraphQL server yet, you can use the server from the tutorial: https://apollo-fullstack-tutorial.herokuapp.com/graphql.
The Apollo Gradle plugin exposes a downloadApolloSchema
task to help you obtain your schema. Provide this task your server's GraphQL endpoint and the output location for the schema.json
file:
# Create a directory for your GraphQL files:
mkdir -p app/src/main/graphql/com/example/
# --schema is interpreted relative to the current working directory. This example
# assumes the root project directory and an Android app in `app`
./gradlew downloadApolloSchema \
--endpoint="https://your.domain/graphql/endpoint" \
--schema="app/src/main/graphql/com/example/schema.graphqls"
If your GraphQL endpoint requires authentication, you can pass custom HTTP headers:
./gradlew downloadApolloSchema \
--endpoint="https://your.domain/graphql/endpoint" \
--schema="app/src/main/graphql/com/example/schema.graphqls" \
--header="Authorization: Bearer $TOKEN"
Add your query
Add your schema.json
and other .graphql
files under src/commonMain/graphql
. Build your module and generated code will be available
under commonMain
sourceSet. That means you can use them both in commonMain
or platform specific Kotlin code. Once the Kotlin plugin builds
the iOS Framework, generated code can even be called from Swift code.
Executing your query
You use an instance of the ApolloClient
class to interact with your server and cache.
To make a query using your generated models:
// First, create an `ApolloClient`
// Replace the serverUrl with your GraphQL endpoint
val apolloClient = ApolloClient(
networkTransport = ApolloHttpNetworkTransport(
serverUrl = "https://your.domain/graphql/endpoint",
headers = mapOf(
"Accept" to "application/json",
"Content-Type" to "application/json",
)
)
)
// in your coroutine scope, call `ApolloClient.query(...).execute()`
scope.launch {
// execute() returns a Flow, here we only take the first item
val response = apolloClient.query(LaunchDetailsQuery(id = "83")).execute().single()
// launch now contains a typesafe model of your data
println("Launch site: ${response.data?.launch?.site"})
}