Skip to content

🤖  A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform.

License

Notifications You must be signed in to change notification settings

JamesSlocumIH/apollo-kotlin

This branch is 443 commits behind apollographql/apollo-kotlin:main.

Folders and files

NameName
Last commit message
Last commit date
Jan 16, 2024
Feb 22, 2024
Feb 28, 2024
May 11, 2023
Feb 9, 2024
Feb 29, 2024
Jan 24, 2024
Mar 1, 2024
Jan 8, 2024
Feb 28, 2024
Feb 29, 2024
Nov 17, 2023
Mar 1, 2024
Dec 14, 2021
Feb 6, 2024
Mar 1, 2024
Apr 30, 2021
Jan 8, 2024
Apr 17, 2023
Dec 12, 2023
Jul 18, 2023
Dec 15, 2023
Mar 6, 2023
Jan 31, 2024
Feb 22, 2024
Jan 9, 2024
Jan 15, 2024
Oct 6, 2023
Feb 28, 2024
May 22, 2023
Jul 10, 2023
Feb 29, 2024

Repository files navigation

Apollo Kotlin

GitHub license Join the community Slack Discord CI Maven Central Gradle Plugin OSS Snapshots Revved up by Develocity

☑️ 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 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 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.

Features

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

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

Maintainers

Documentation

Check the project website for in depth documentation.

Getting started

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.4"
}

Add the runtime dependency:

dependencies {
  implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.4")
}

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:

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

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.

Releases

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 {
  mavenCentral()
}

dependencies {
  implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.4")

  // optional: if you want to use the normalized cache
  implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.4")
  // 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.4")
}

Snapshots

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.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

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

Additional resources

Who is Apollo?

Apollo builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:

  • Apollo Studio – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes.
  • Apollo Federation – The industry-standard open architecture for building a distributed graph. Use Apollo’s gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services.
  • Apollo Client – The most popular GraphQL client for the web. Apollo also builds and maintains Apollo iOS and Apollo Kotlin.
  • Apollo Server – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.

Learn how to build with Apollo

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.

About

🤖  A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Kotlin 92.4%
  • Java 6.6%
  • Other 1.0%