Advanced workflows

Amplify Android v1 is deprecated as of June 1st, 2024. No new features or bug fixes will be added. Dependencies may become outdated and potentially introduce compatibility issues.

Please use the latest version (v2) of Amplify Library for Android to get started. Refer to the upgrade guide for instructions on upgrading your application to the latest version.

Amplify libraries should be used for all new cloud connected applications. If you are currently using the AWS Mobile SDK for Android, you can access the documentation here.

This section describes different use cases for constructing your own custom GraphQL requests and how to approach it. You may want to construct your own GraphQL request if you want to

retrieve only a subset of the data to reduce data transfer
retrieve nested objects at a depth that you choose
combine multiple operations into a single request
send custom headers to your AppSync endpoint

A GraphQL request is automatically generated for you when using AWSAPIPlugin with the existing workflow. For example, if you have a Todo model, a mutation request to save the Todo will look like this:

Todo todo = Todo.builder()
    .name("My first todo")
    .description("todo description")
    .build();
Amplify.API.mutate(ModelMutation.create(todo),
    result -> Log.i("ApiDemo", "Mutation succeeded."),
    failure -> Log.e("ApiDemo", "Mutation failed.", failure)

val todo = Todo.builder()
    .name("My first todo")
    .description("todo description")
    .build()
Amplify.API.mutate(ModelMutation.create(todo),
    { Log.i("ApiDemo", "Mutation succeeded") },
    { Log.e("ApiDemo", "Mutation failed", it) }

val todo = Todo.builder()
    .name("My first todo")
    .description("todo description")
    .build()
    val result = Amplify.API.mutate(ModelMutation.create(todo))
    Log.i("ApiDemo", "Mutation succeeded") 
} catch (error: ApiException) {
    Log.e("ApiDemo", "Mutation failed", error) 

Todo todo = Todo.builder()
    .name("My first todo")
    .description("todo description")
    .build();
Amplify.API.mutate(ModelMutation.create(todo))
    .subscribe(
        result -> Log.i("ApiDemo", "Mutation succeeded"),
        failure -> Log.e("ApiDemo", "Mutation failed", failure)

Underneath the covers, a request is generated with a GraphQL document and variables and sent to the AppSync service.

  "query": "mutation createTodo($input: CreateTodoInput!) {
    createTodo(input: $input) {
      description
  "variables": "{
    "input": {
      "id": "[UNIQUE-ID]",
      "name": "my first todo",
      "description": "todo description"

The different parts of the document are described as follows

mutation - the operation type to be performed, other operation types are query and subscription
createTodo($input: CreateTodoInput!) - the name and input of the operation.
$input: CreateTodoInput! - the input of type CreateTodoInput! referencing the variables containing JSON input
createTodo(input: $input) - the mutation operation which takes a variable input from $input
the selection set containing id, name, and description are fields specified to be returned in the response

You can learn more about the structure of a request from GraphQL Query Language and AppSync documentation. To test out constructing your own requests, open the AppSync console using amplify console api and navigate to the Queries tab.

Subset of data

The selection set of the document specifies which fields are returned in the response. For example, if you are displaying a view of the Todo without the description, you can construct the document to omit the field. You can learn more about selection sets here.

query getTodo($id: ID!) {
  getTodo(id: $id) {

The response data will look like this

  "data": {
    "getTodo": {
      "id": "111",
      "name": "my first todo"

First, create your own GraphQLRequest

private GraphQLRequest<Todo> getTodoRequest(String id) {
    String document = "query getTodo($id: ID!) { "
        + "getTodo(id: $id) { "
            + "id "
            + "name "
        + "}"
    return new SimpleGraphQLRequest<>(
            document,
            Collections.singletonMap("id", id),
            Todo.class,
            new GsonVariablesSerializer());

private fun getTodoRequest(id: String): GraphQLRequest<Todo> {
    val document = ("query getTodo(\$id: ID!) { "
          + "getTodo(id: \$id) { "
              + "id "
              + "name "
            + "}"
          + "}")
    return SimpleGraphQLRequest(
            document,
            mapOf("id" to id),
            Todo::class.java,
            GsonVariablesSerializer())

Then, query for the Todo by a todo id

Amplify.API.query(getTodoRequest("[TODO_ID]"),
    response -> Log.d("MyAmplifyApp", "response" + response),
    error -> Log.e("MyAmplifyApp", "error" + error)

Amplify.API.query(getTodoRequest("[TODO_ID]"),
    { Log.d("MyAmplifyApp", "Response = $it") },
    { Log.e("MyAmplifyApp", "Error!", it) }

    val response = Amplify.API.query(getTodoRequest("[TODO_ID]"))
    Log.d("MyAmplifyApp", "Query response = $response")
} catch (error: ApiException) {
    Log.e("MyAmplifyApp", "Query failed", error)

Nested Data

If you have a relational model, you can retrieve the nested object by creating a GraphQLRequest with a selection set containing the nested object's fields. For example, in this schema, the Post can contain multiple comments and notes.

enum PostStatus {
type Post @model {
  title: String!
  rating: Int!
  status: PostStatus!
  comments: [Comment] @hasMany(indexName: "byPost", fields: ["id"])
  notes: [Note] @hasMany(indexName: "byNote", fields: ["id"])
type Comment @model {
  postID: ID! @index(name: "byPost", sortKeyFields: ["content"])
  post: Post! @belongsTo(fields: ["postID"])
  content: String!
type Note @model {
  postID: ID! @index(name: "byNote", sortKeyFields: ["content"])
  post: Post! @belongsTo(fields: ["postID"])
  content: String!

If you only want to retrieve the comments, without the notes, create a GraphQLRequest for the Post with nested fields only containing the comment fields.

private GraphQLRequest<Post> getPostWithCommentsRequest(String id) {
    String document = "query getPost($id: ID!) { "
        + "getPost(id: $id) { "
            + "id "
            + "title "
            + "rating "
            + "status "
            + "comments { "
                + "items { "
                    + "postID "
                    + "content "
            + "} "
        + "} "
    return new SimpleGraphQLRequest<>(
            document,
            Collections.singletonMap("id", id),
            Post.class,
            new GsonVariablesSerializer());

private fun getPostWithCommentsRequest(id: String): GraphQLRequest<Post> {
    val document = ("query getPost(\$id: ID!) { "
        + "getPost(id: \$id) { "
            + "id "
            + "title "
            + "rating "
            + "status "
            + "comments { "
                + "items { "
                    + "postID "
                    + "content "
            + "} "
        + "} "
    return SimpleGraphQLRequest(
            document,
            mapOf("id" to id),
            Post::class.java,
            GsonVariablesSerializer())

Then query for the Post:

Amplify.API.query(getPostWithCommentsRequest("[POST_ID]"),
    response -> Log.d("MyAmplifyApp", "response" + response),
    error -> Log.e("MyAmplifyApp", "error" + error)

Amplify.API.query(getPostWithCommentsRequest("[POST_ID]"),
    { Log.d("MyAmplifyApp", "Response = $it") },
    { Log.e("MyAmplifyApp", "Error!", it) }

    val response = Amplify.API.query(getPostWithCommentsRequest("[POST_ID]"))
    Log.d("MyAmplifyApp", "Query response = $response")
} catch (error: ApiException) {
    Log.e("MyAmplifyApp", "Query error", error)

Combining Multiple Operations

When you want to perform more than one operation in a single request, you can place them within the same document. For example, to retrieve a Post and a Todo

private GraphQLRequest<String> getPostAndTodo(String postId, String todoId) {
    String document = "query get($postId: ID!, $todoId: ID!) { "
        + "getPost(id: $postId) { "
            + "id "
            + "title "
            + "rating "
        + "} "
        + "getTodo(id: $todoId) { "
            + "id "
            + "name "
        + "} "
    Map<String, Object> variables = new HashMap<>();
    variables.put("postId", postId);
    variables.put("todoId", todoId);
    return new SimpleGraphQLRequest<>(
            document,
            variables,
            String.class,
            new GsonVariablesSerializer());

private fun getPostAndTodo(postId: String, todoId: String): GraphQLRequest<String> {
    val document = ("query get(\$postId: ID!, \$todoId: ID!) { "
            + "getPost(id: \$postId) { "
                + "id "
                + "title "
                + "rating "
            + "} "
            + "getTodo(id: \$todoId) { "
                + "id "
                + "name "
            + "} "
        + "}")
    return SimpleGraphQLRequest(
            document,
            mapOf("postId" to postId, "todoId" to todoId),
            String::class.java,
            GsonVariablesSerializer())

Adding Headers to Outgoing Requests

By default, the API plugin includes appropriate authorization headers on your outgoing requests. However, you may have an advanced use case where you wish to send additional request headers to AppSync.

To specify your own headers, use the configureClient() configuration option on the AWSApiPlugin's builder. Specify the name of one of the configured APIs in your amplifyconfiguration.json. Apply customizations to the underlying OkHttp instance by providing a lambda expression as below.

AWSApiPlugin plugin = AWSApiPlugin.builder()
    .configureClient("yourApiName", okHttpBuilder -> {
        okHttpBuilder.addInterceptor(chain -> {
            Request originalRequest = chain.request();
            Request updatedRequest = originalRequest.newBuilder()
                .addHeader("customHeader", "someValue")
                .build();
            return chain.proceed(updatedRequest);
        });
    .build();
Amplify.addPlugin(plugin);

val plugin = AWSApiPlugin.builder()
    .configureClient("yourApiName") { okHttpBuilder ->
        okHttpBuilder.addInterceptor { chain ->
            val originalRequest = chain.request()
            val updatedRequest = originalRequest.newBuilder()
                .addHeader("customHeader", "someValue")
                .build()
            chain.proceed(updatedRequest)
    .build()
Amplify.addPlugin(plugin)

val plugin = AWSApiPlugin.builder()
    .configureClient("yourApiName") { okHttpBuilder ->
        okHttpBuilder.addInterceptor { chain ->
            val originalRequest = chain.request()
            val updatedRequest = originalRequest.newBuilder()
                .addHeader("customHeader", "someValue")
                .build()
            chain.proceed(updatedRequest)
    .build()
Amplify.addPlugin(plugin)

AWSApiPlugin plugin = AWSApiPlugin.builder()
    .configureClient("yourApiName", okHttpBuilder -> {
        okHttpBuilder.addInterceptor(chain -> {
            Request originalRequest = chain.request();
            Request updatedRequest = originalRequest.newBuilder()
                .addHeader("customHeader", "someValue")
                .build();
            return chain.proceed(updatedRequest);
        });
    .build();
RxAmplify.addPlugin(plugin);