/
Launch Apollo Studio

Mutations


Queries are useful to fetch data from a server, but client-server communication may also require sending data to the server. This is where Mutations become handy. Just like REST, any request might end up causing some side-effects on the server, but by convention it's suggested that one doesn't use GET requests to modify data. GraphQL is similar - technically any query could be implemented to cause a data write. However, it's useful to establish a convention that any operations that cause writes should be sent explicitly via a mutation.

Apollo Android handles GraphQL mutations. Mutations are similar to queries in syntax, the only difference being that you use the keyword mutation instead of query to indicate that the root fields on this query are going to be performing writes to the backend.

mutation UpvotePost($postId: Int!) {
  upvotePost(postId: $postId) {
    votes
  }
}

GraphQL mutations represent two things in one query string:

  1. The mutation field name with arguments, upvotePost, which represents the actual operation to be done on the server
  2. The fields you want back from the result of the mutation to update the client: { votes }

The above mutation will upvote a post on the server. The result might be:

{
  "data": {
    "upvotePost": {
      "id": "123",
      "votes": 5
    }
  }
}

Similar to queries, mutations are represented by instances of generated classes, conforming to the ApolloMutationCall interface. Constructor arguments are used to define mutation variables. You pass a mutation object to ApolloClient#perform(mutation) to send the mutation to the server, execute it, and receive typed results:

val upvotePostMutation = UpvotePostMutation(votes = 3)

apolloClient
    .mutate(upvotePostMutation)
    .enqueue(object: ApolloCall.Callback<UpvotePost.Data>() {
            override fun onFailure(e: ApolloException) {
                Log.i(TAG, response.toString());
            }

            override fun onResponse(response: Response<UpvotePost.Data>) {
                Log.e(TAG, e.getMessage(), e);
            }
        }
    )

Using fragments in mutation results

In many cases, you'll want to use mutation results to update your UI. Fragments can be a great way of sharing result handling between queries and mutations:

mutation UpvotePost($postId: Int!) {
  upvotePost(postId: $postId) {
    ...PostDetails
  }
}
apolloClient
    .mutate(upvotePostMutation)
    .enqueue(object: ApolloCall.Callback<UpvotePost.Data>() {
            override fun onFailure(e: ApolloException) {
                Log.i(TAG, response.data.upvotePost.fragments.postDetails);
            }

            override fun onResponse(response: Response<UpvotePost.Data>) {
                Log.e(TAG, e.getMessage(), e);
            }
        }
    )

Passing input objects

The GraphQL type system includes input objects as a way to pass complex values to fields. Input objects are often defined as mutation variables, because they give you a compact way to pass in objects to be created:

mutation CreateReviewForEpisode($episode: Episode!, $review: ReviewInput!) {
  createReview(episode: $episode, review: $review) {
    stars
    commentary
  }
}
val reviewInput = ReviewInput(stars = 5, commentary = "This is a great movie!")

apolloClient.mutate(CreateReviewForEpisodeMutation(episode = Episode.NEWHOPE, review = reviewInput))

Designing mutation results

In GraphQL, mutations can return any type, and that type can be queried just like a regular GraphQL query. So the question is - what type should a particular mutation return?

In most cases, the data available from a mutation result should be the server developer's best guess of the data a client would need to understand what happened on the server. For example, a mutation that creates a new comment on a blog post might return the comment itself. A mutation that reorders an array might need to return the whole array.

Uploading files

Apollo Android supports file uploading over graphql-multipart-request-spec.

You need to define this mapping in your build.gradle file.

apollo {
  customTypeMapping = [
    "Upload" : "com.apollographql.apollo.api.FileUpload"
  ]
}

Note You don't need to register custom type adapter for FileUpload.

In this example, the GraphQL schema uses custom scalar type named Upload for file upload. Change it to match your GraphQL schema.

Create graphql mutation.

mutation SingleUpload($file: Upload!) {
  singleUpload(file: $file) {
    id
    path
    filename
    mimetype
  }
}

Call your mutation with mimetype and a valid File.

  mutationSingle = SingleUploadMutation(file = FileUpload("image/jpg", File("/my/image.jpg")))
Edit on GitHub