Get started

Learn how to quickly set up Apollo Client in your Android app

Apollo-Android is a GraphQL compliant client that generates Java models from standard GraphQL queries. These models give you a typesafe API to work with GraphQL servers. Apollo will help you keep your GraphQL query statements together, organized, and easily accessible from Java.

When you change a query and recompile your project - the Apollo code generator will rebuild your data model for you. Code generation also allows Apollo to read and unmarshal responses from the network without the need of any reflection.

Installation

The latest Gradle plugin version is

To use this plugin, add the dependency to your project's build.gradle file:

Downloading a Schema

Apollo Android requires a GraphQL schema file as input to the code generation process. A schema file is a JSON file that contains the results of an introspection query. Conventionally this file is called schema.json, and you store it next to your .graphql files. Most users keep these files in the /src/main/graphql directory.

You can use apollo-codegen to download a GraphQL schema. This works by sending an introspection query to your server:

Note: In the sample project you can find the schema here => apollo-sample/src/main/graphql/com/apollographql/apollo/sample/schema.json.

Creating a Client

With the installation complete and schema downloaded, let's create your Apollo Client. In most cases, you’ll want to create a single shared instance of ApolloClient and point it at your GraphQL server. ApolloClient uses OkHttp under the hood for handling network requests. So you will need to create an instance of the OkHttpClient and pass it to the ApolloClient builder.

If you need to send header values with your GraphQL requests, you can add those to your OkHttpClient instance by means of an Interceptor.

Note: In the sample project you can find the client here => apollo-sample/src/main/java/com/apollographql/apollo/sample/GitHuntApplication.java.

That's it! Now your client is ready to start fetching data.

Creating a .graphql File

The Apollo Android plugin works by generating code that corresponds to the GraphQL queries you specify in your application's .graphql files. There is nothing Android specific about these queries, they can be used with other GraphQL clients as well. It is however important to have a name for your query to avoid compilation failures.

So if you wanted to perform the below query, you would place it in a file that ends in .graphql. It's common to use the query name as the file name. So in this case your file would be named, FeedQuery.graphql.

Note: For the sample project you can find the .graphql files here => apollo-sample/src/main/graphql/com/apollographql/apollo/sample.

Code Generation

To have Apollo generate the appropriate Java classes for you, you will need to compile your code. Based on your downloaded schema.json file and the contents of your .graphql files you will have generated Java classes in the following directory build/generated/source/apollo. There will be one Java class for each of your queries with nested classes for reading the network response.

Note: These are Apollo generated files. Therefore they should not be modified.

Consuming Code

You can use the generated classes to make requests to your GraphQL API. ApolloClient can take as input any Query or Mutation that you have generated using Apollo.

First, you would create an instance of your desired query or mutation class. This class was generated for you as part of the Apollo code gen process. You can either use the associated builder() method or create the class directly via its constructor.

Then you can pass that query into the query() method available on the ApolloClient instance and enqueue your request. Once the request is completed you will have access to the data inside of the onResponse() method. Mutations work in the same way, except that you would use the mutate() method on the ApolloClient instance.