GraphQL is a query language that offers an alternative model to developing APIs (REST, SOAP or gRPC) with detailed description.
In this tutorial, we're gonna build a Spring Boot GraphQL example with H2 database that will expose CRUD APIs to create, read, update and delete objects with the help of graphql-spring-boot-starter
and Spring Data JPA.
Related Post:
- Spring Boot + GraphQL + MySQL example
- Spring Boot + GraphQL + PostgreSQL example
- Spring Boot + GraphQL + MongoDB example
- Spring Boot 3 Rest API example: CRUD Application
- Spring Boot Security: Login and Registration example with JWT
- Spring Boot Thymeleaf CRUD example
- Documentation: Spring Boot Swagger 3 example
- Unit Test: @DataJpaTest example for Spring Data Repository
- Caching: Spring Boot Redis Cache example
Spring Boot GraphQL example
Overview
We have two data models: Author and Tutorial.
Author {
id: Long
name: String
age: Integer
}
Tutorial {
id: Long
title: String
description: String
author: Author
}
One Author will have many Tutorials, so it is One-to-Many relationship.
The goal of this example is to build a GraphQL APIs to do CRUD operations with H2 database using only one endpoint: /apis/graphql
.
The Spring Boot GraphQL Starter will make GraphQL server running in a short time.
CRUD GraphQL APIs
- Create an Author: GraphQL
mutation {
createAuthor(
name: "bezkoder",
age: 27) {
id name
}
}
Response
{
"data": {
"createAuthor": {
"id": "1",
"name": "bezkoder"
}
}
}
- Create a Tutorial: GraphQL: we want response including Tutorial id, title and author (name)
mutation {
createTutorial (
title: "Tutorial #1",
description: "Description for Tut#1"
author: 1)
{
id title author { name }
}
}
Response
{
"data": {
"createTutorial": {
"id": "1",
"title": "Tutorial #1",
"author": {
"name": "bezkoder"
}
}
}
}
- Read all Authors: GraphQL
{
findAllAuthors{
id
name
age
}
}
Response
{
"data": {
"findAllAuthors": [
{
"id": "1",
"name": "bezkoder",
"age": 27
},
{
"id": "2",
"name": "zKoder",
"age": 30
}
]
}
}
- Read all Tutorials: GraphQL
{
findAllTutorials{
id
title
description
author{
id
name
}
}
}
Response
{
"data": {
"findAllTutorials": [
{
"id": "1",
"title": "Tutorial #1",
"description": "Description for Tut#1",
"author": {
"id": "1",
"name": "bezkoder"
}
},
{
"id": "2",
"title": "Tutorial #2",
"description": "Description for Tut#2",
"author": {
"id": "1",
"name": "bezkoder"
}
},
{
"id": "3",
"title": "Tutorial #3",
"description": "Description for Tut#3",
"author": {
"id": "2",
"name": "zKoder"
}
}
]
}
}
- Update a Tutorial: GraphQL
mutation {
updateTutorial (
id: 2
description: "updated Desc Tut#2")
{
id title description author { name }
}
}
Response
{
"data": {
"updateTutorial": {
"id": "2",
"title": "Tutorial #2",
"description": "updated Desc Tut#2",
"author": {
"name": "bezkoder"
}
}
}
}
- Delete a Tutorial: GraphQL
mutation {
deleteTutorial(id: 1)
}
Response
{
"data": {
"deleteTutorial": true
}
}
- Count number of Tutorials: GraphQL
{
countTutorials
}
Response
{
"data": {
"countTutorials": 2
}
}
If you check H2 database, it will have 2 tables: author and tutorial.
The content inside these tables looks like:
Step by step to build Spring Boot GraphQL example
Technology
Our Spring Boot application will use:
- Java 17 / 11 / 8
- Spring Boot 3 / 2 (with Spring Web, Spring Data JPA)
- graphql-spring-boot-starter 15.0.0
- graphql-java-tools 5.2.4
- Maven 3.6.1
- H2 database
Project Structure
This is folders & files structure for our Spring Boot + GraphQL application:
-
resources/graphql contains
.graphqls
files that define GraphQL chemas. -
model holds two Entities:
Author
andTutorial
. - repository contains Repository interfaces to interact with H2 database.
-
resolver resolves values for query & mutation requests by implementing some
Resolver
interfaces from GraphQL Java Tools. - application.properties configures Spring Datasource, Spring Data JPA and GraphQL base Url.
- pom.xml includes dependencies for the whole project.
Set up the project
Create new Spring Boot project using Spring Tool Suite or going to https://start.spring.io/.
Then add these dependencies to pom.xml file:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.graphql-java-kickstart</groupId>
<artifactId>graphql-spring-boot-starter</artifactId>
<version>15.0.0</version>
</dependency>
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java-tools</artifactId>
<version>5.2.4</version>
</dependency>
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java-extended-scalars</artifactId>
<version>21.0</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>
Configure Spring Datasource, JPA, GraphQL
Open application.properties and add the following configuration.
spring.h2.console.enabled=true
# default path: h2-console
spring.h2.console.path=/h2-ui
spring.datasource.url=jdbc:h2:file:./testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto= update
# Graphql
graphql.servlet.mapping: /apis/graphql
-
spring.datasource.url
:jdbc:h2:mem:[database-name]
for In-memory database andjdbc:h2:file:[path/database-name]
for disk-based database. - We configure
H2Dialect
for H2 Database -
spring.h2.console.enabled=true
tells the Spring to start H2 Database administration tool and you can access this tool on the browser:http://localhost:8080/h2-console
. -
spring.h2.console.path=/h2-ui
is for H2 console's url, so the default urlhttp://localhost:8080/h2-console
will change tohttp://localhost:8080/h2-ui
.
By default, Spring Boot GraphQL starter exposes the GraphQL Service on /graphql
endpoint for HTTP POST requests containing the GraphQL payload. In the code above, we config the endpoint with new base url: /apis/graphql
.
Extend Scalars for graphql-java Long type
The implementation of GraphQL Java doesn't provide a Long scalar type by default. So we need to use the graphql-java-extended-scalars
package that provides a GraphQLLong
scalar type definition which represents java.lang.Long
.
Open SpringBootGraphqlApplication.java and add a Bean named extendedScalarLong()
:
@SpringBootApplication
public class SpringBootGraphqlApplication {
// ...
@Bean
public graphql.schema.GraphQLScalarType extendedScalarLong() {
return graphql.scalars.ExtendedScalars.GraphQLLong;
}
}
Create GraphQL Schema
We're gonna split up your schema into two .graphqls
files. The Spring Boot GraphQL starter will automatically find these schema files.
Under src/main/resources folder, create author.graphqls and tutorial.graphqls files.
author.graphqls
scalar Long
type Author {
id: ID!
name: String!
age: Int
}
# Root
type Query {
findAllAuthors: [Author]!
countAuthors: Long!
}
# Root
type Mutation {
createAuthor(name: String!, age: Int): Author!
}
GraphQL accepts only one root Query
and one root Mutation
types, so we need to bring all the query and mutation operations into the root Types. But in the schemas above, we want to split the logic for each model. How to do this? We extend the Query
and Mutation
types.
tutorial.graphqls
type Tutorial {
id: ID!
title: String!
description: String
author: Author
}
extend type Query {
findAllTutorials: [Tutorial]!
countTutorials: Long!
}
extend type Mutation {
createTutorial(title: String!, description: String, author: ID!): Tutorial!
updateTutorial(id: ID!, title: String, description: String): Tutorial!
deleteTutorial(id: ID!): Boolean
}
The "!" at the end of some fields indicates non-nullable type. If we don't use it, GraphQL accepts null
value in the response.
Define Data Models
Now we define twom main models with One-to-Many Relationship in model package:
- Author: id, name, age
- Tutorial: id, title, description, author_id
Author.java
package com.bezkoder.spring.graphql.model;
// import javax.persistence.*;
import jakarta.persistence.*; // for Spring Boot 3
@Entity
public class Author {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;
@Column(name = "name", nullable = false)
private String name;
@Column(name = "age")
private Integer age;
public Author() {
}
public Author(Long id) {
this.id = id;
}
public Author(String name, Integer age) {
this.name = name;
this.age = age;
}
public Long getId() {
return id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
@Override
public String toString() {
return "User [id=" + id + ", name=" + name + ", age=" + age + "]";
}
}
Tutorial.java
package com.bezkoder.spring.graphql.model;
// import javax.persistence.*;
import jakarta.persistence.*; // for Spring Boot 3
@Entity
public class Tutorial {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;
@Column(name = "title", nullable = false)
private String title;
@Column(name = "description")
private String description;
@ManyToOne
@JoinColumn(name = "author_id", nullable = false, updatable = false)
private Author author;
public Tutorial() {
}
public Tutorial(String title, String description, Author author) {
this.title = title;
this.description = description;
this.author = author;
}
public Long getId() {
return id;
}
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
public String getDescription() {
return description;
}
public void setDescription(String description) {
this.description = description;
}
public Author getAuthor() {
return author;
}
public void setAuthor(Author author) {
this.author = author;
}
@Override
public String toString() {
return "Tutorial [id=" + id + ", title=" + title + ", description=" + description + ", author=" + author + "]";
}
}
Create Repositories
In repository package, create two interfaces that implement JpaRepository
.
AuthorRepository.java
package com.bezkoder.spring.graphql.repository;
import org.springframework.data.jpa.repository.JpaRepository;
import com.bezkoder.spring.graphql.model.Author;
public interface AuthorRepository extends JpaRepository<Author, Long> {
}
TutorialRepository.java
package com.bezkoder.spring.graphql.repository;
import org.springframework.data.jpa.repository.JpaRepository;
import com.bezkoder.spring.graphql.model.Tutorial;
public interface TutorialRepository extends JpaRepository<Tutorial, Long> {
}
Once we extends the JpaRepository
, Spring Data JPA will automatically generate implementation with find, save, delete, count methods for the entities.
Implement GraphQL Root Query Resolver
Every field in the schema root query should have a method in the Query Resolver class with the same name.
Now look back to the schemas we defined above.
# author.graphqls
type Query {
findAllAuthors: [Author]!
countAuthors: Long!
}
# tutorial.graphqls
extend type Query {
findAllTutorials: [Tutorial]!
countTutorials: Long!
}
This Query
class implements GraphQLQueryResolver
. We don't want to use GraphQLLong
for countAuthors
and countTutorials
return type, so we alias it by using newAliasedScalar("Long")
.
resolver/Query.java
package com.bezkoder.spring.graphql.resolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import com.bezkoder.spring.graphql.model.Author;
import com.bezkoder.spring.graphql.model.Tutorial;
import com.bezkoder.spring.graphql.repository.AuthorRepository;
import com.bezkoder.spring.graphql.repository.TutorialRepository;
import graphql.kickstart.tools.GraphQLQueryResolver;
import graphql.scalars.ExtendedScalars;
import graphql.schema.GraphQLScalarType;
@Component
public class Query implements GraphQLQueryResolver {
private AuthorRepository authorRepository;
private TutorialRepository tutorialRepository;
GraphQLScalarType longScalar = ExtendedScalars.newAliasedScalar("Long")
.aliasedScalar(ExtendedScalars.GraphQLLong)
.build();
@Autowired
public Query(AuthorRepository authorRepository, TutorialRepository tutorialRepository) {
this.authorRepository = authorRepository;
this.tutorialRepository = tutorialRepository;
}
public Iterable<Author> findAllAuthors() {
return authorRepository.findAll();
}
public Iterable<Tutorial> findAllTutorials() {
return tutorialRepository.findAll();
}
public long countAuthors() {
return authorRepository.count();
}
public long countTutorials() {
return tutorialRepository.count();
}
}
Implement GraphQL Root Mutation Resolver
Mutation class will implement GraphQLMutationResolver
.
Just like Query Resolver, every field in the schema mutation query should have a method in the Mutation Resolver class with the same name.
resolver/Mutation.java
package com.bezkoder.spring.graphql.resolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import com.bezkoder.spring.graphql.model.Author;
import com.bezkoder.spring.graphql.model.Tutorial;
import com.bezkoder.spring.graphql.repository.AuthorRepository;
import com.bezkoder.spring.graphql.repository.TutorialRepository;
import graphql.kickstart.tools.GraphQLMutationResolver;
import jakarta.persistence.EntityNotFoundException;
@Component
public class Mutation implements GraphQLMutationResolver {
private AuthorRepository authorRepository;
private TutorialRepository tutorialRepository;
@Autowired
public Mutation(AuthorRepository authorRepository, TutorialRepository tutorialRepository) {
this.authorRepository = authorRepository;
this.tutorialRepository = tutorialRepository;
}
public Author createAuthor(String name, Integer age) {
Author author = new Author();
author.setName(name);
author.setAge(age);
authorRepository.save(author);
return author;
}
public Tutorial createTutorial(String title, String description, Long authorId) {
Tutorial tutorial = new Tutorial();
tutorial.setAuthor(new Author(authorId));
tutorial.setTitle(title);
tutorial.setDescription(description);
tutorialRepository.save(tutorial);
return tutorial;
}
public boolean deleteTutorial(Long id) {
tutorialRepository.deleteById(id);
return true;
}
public Tutorial updateTutorial(Long id, String title, String description) throws EntityNotFoundException {
Optional<Tutorial> optTutorial = tutorialRepository.findById(id);
if (optTutorial.isPresent()) {
Tutorial tutorial = optTutorial.get();
if (title != null)
tutorial.setTitle(title);
if (description != null)
tutorial.setDescription(description);
tutorialRepository.save(tutorial);
return tutorial;
}
throw new EntityNotFoundException("Not found Tutorial to update!");
}
}
Implement GraphQL Field Resolver
For complex fields like author
in Tutorial
, we have to resolve the value of those fields.
TutorialResolver
implements GraphQLResolver
interface and has getAuthor()
method.
resolver/TutorialResolver.java
package com.bezkoder.spring.graphql.resolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import com.bezkoder.spring.graphql.model.Author;
import com.bezkoder.spring.graphql.model.Tutorial;
import com.bezkoder.spring.graphql.repository.AuthorRepository;
import graphql.kickstart.tools.GraphQLResolver;
@Component
public class TutorialResolver implements GraphQLResolver<Tutorial> {
@Autowired
private AuthorRepository authorRepository;
public TutorialResolver(AuthorRepository authorRepository) {
this.authorRepository = authorRepository;
}
public Author getAuthor(Tutorial tutorial) {
return authorRepository.findById(tutorial.getAuthor().getId()).orElseThrow(null);
}
}
If the client want to get a Tutorial
without author
field, the GraphQL Server will never do the work to retrieve it. So the getAuthor()
method above will never be executed.
Run & Check result
Run Spring Boot application with command: mvn spring-boot:run
Tables will be automatically generated in Database.
If you check H2 database (by open browser with url: http://localhost:8080/h2-ui/
):
Click on Connect button, and you can see them.
For checking result, you can use Postman to make HTTP POST request to http://localhost:8080/apis/graphql
.
Conclusion
As an alternative approach to REST APIs, GraphQL minimize complexity between client & server.
Today we've learned how to use Spring Boot GraphQL Starter and the GraphQL Java Tools to build GraphQL Apis. Our Spring Boot project also can communicate with H2 database using Spring Data JPA.
Happy learning! See you again.
Further Reading
- GraphQL documentation
- https://www.graphql-java.com/tutorials/getting-started-with-spring-boot/
- graphql-java Github
Source Code
You can find the complete source code for this tutorial on Github.
Other databases:
- Spring Boot + GraphQL + MySQL example
- Spring Boot + GraphQL + PostgreSQL example
- Spring Boot + GraphQL + MongoDB example
Security: Spring Boot Security: Login and Registration example with JWT
Unit Test: @DataJpaTest example for Spring Data Repository
Documentation: Spring Boot + Swagger 3 example (with OpenAPI 3)
Caching: Spring Boot Redis Cache example
Top comments (0)