Spring Boot + GraphQL example

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.

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 and Tutorial.
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 and jdbc: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 url http://localhost:8080/h2-console will change to http://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.

Source Code

You can find the complete source code for this tutorial on Github.

Other databases:

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

Blog

Spring Boot + GraphQL example

Tien Nguyen