Spring for GraphQL Mutation
In earlier articles, we talked about GraphQL queries. But, GraphQL is not just about queries.
Like any other API platform, a GraphQL service also needs to provide a way to manipulate data. This is where GraphQL mutation comes into the picture.
In theory, we can use GraphQL queries to modify the state but this will confuse our API consumers.
In REST, we use GET request to retrieve data, and by convention, it should not cause any side-effect. Similarly, we should not use GraphQL queries to modify the application’s state.
Therefore, if we need to provide APIs that change state, we should use mutation instead.
Read more about GraphQL..
Getting started with Spring Boot GraphQL service
What is GraphQL Mutation?
In GraphQL, a mutation is used to insert, update or delete data. The mutation API is defined with the type Mutation rather than the Query.
An example of a mutation that adds a book to the book catalog.
In the above example, addBook API is a mutation; it allows you to add/save a book and returns the ID of the book after a successful save.
! means a required field.
Similarly, we can define API to update the book as:
And, to delete the book:
We can even design APIs to return info about added, updated, or deleted books as:
Where type BookInfo is defined as:
In GraphiQL, you can add a book using mutation as:
GraphQL Mutation Input Type
Instead of defining the API with scalar arguments, for example — addBook(name: String!, author: String!, publisher: String!,price: Float!), you can define a complex object called input type. This is useful if you want to reuse the input type for both updates and inserts.
An input type is defined with a keyword input instead of type as:
As a result, we can change the API definition as:
And, in GraphiQL (or other clients), we can call API as:
Implementing Mutations in Spring
In Spring for GraphQL, we can implement mutation using @SchemaMapping or @MutationMapping.
A GraphQL API addBook,
can be implemented by defining @SchemaMapping with typeName as Mutation as:
Generally, we can leave the parameter field if the method name is the same as the field, as:
Similar to @QueryMapping, Spring also provides a shorthand annotation as @MutationMapping. As a result, we can write addBook mutation as:
As always, you can test the API in GraphiQL at http://localhost:8080/graphiql?path=/graphql
Implementing Mutation with Input Type
If a mutation is defined as:
Then, we can implement mutation by defining @MutationMapping and @Argument as:
Code Example
The working code example of this article is listed on GitHub. To run the example, clone the repository, and import graphql-spring-mutation as a project in your favorite IDE as a Gradle project.
The code use Spring JPA to store data in the in-memory H2 database. You can find more information in READMe.md
Conclusion
GraphQL mutation is used to change the state of the application (insert, update and delete). In Spring for GraphQL, a mutation can be implemented by defining a handler method by using annotation @MutationMapping or @SchemaMapping with the parameter typeName as Mutation.
Originally published at https://techdozo.dev on August 14, 2022.
