Getting started with GraphQL & Spring Boot tutorial in Java

In this tutorial, we’ll be using 3 libraries in order to achieve a seamless implementation of GraphQL:

- SpringBoot
- GraphQL
- Lombok (Annotation processing)
- Redis (For security) (optional)
- Spring-security (for security) (optional)

What is GraphQL?

GraphQL is a query language created by FaceBook, which allows your frontend to create queries without the need of defining backend endpoints for your database. This means that the client has much more flexibility on the data that it wants to query.

Why use GraphQL?

Compared to traditional REST apis, GraphQL has a lot to offer:

What are the advantages of using Graphql

Flexibility in the specified fields because the ui client defines the query

The front end designers can determine when building their queries what data they need from the object, rather than returning the entire object like we do in rest. This gives more power to the UI Team to build efficient and fast applications.

Single API Endpoint

Only one endpoint url for the backend /graphql (no need to write several endpoints)

Frontend & Backend share the same schema definition

Backend can notify the front end of changes via subscription

Subscriptions - Unlike queries, you can create a subscription which makes a websocket connection to your backend, and notifies the frontend when data has changed. (See this for more)

Reusability on the client side

The client side has immediate access to the new schema defined in graphql as soon as those definitions are released. The UI client code can access those schema through its existing code, without modification, except maybe to know what to do with the data.

- Reusability - Once you define an object in the GraphQL schema, you’ll always be able to query that data, as compared to defining another endpoint using a restful api.

What are the disadvantages of using Graphql

Bad UI Choices could be a liability

Because the UI designer choose what to fetch rather than a hardcoded endpoint, it would be easy to over fetch - retrieving data that is not needed by the UI. Possible overhead

- Since there is only one endpoint, the client defines the query which defines the shape and size of the data retrieved, so you’ll have to manage what the client sends.

Learning Curve

If the team is used to using Rest, there could be a slight learning curve for the API Developer and UI Developers to learn new processes.

Security

In Spring Security, security is managed out of the box by the rest endpoints. Graphql is not using the rest endpoints this creates a security concern and possibly a duplication of our security business logic.

Make sure that input is vaidated and secured - for example in rest by default we may have a limit of 20 pages, but grqphl won’t inherit that limitation, so if someone asked for 10,000 pages it could be a problem if precautions are not made.

Setting up GraphQL in Spring Boot (Backend)

Setting up dependencies

In this tutorial we’ll be setting up our project using Gradle Kotlin (you can decide to use Gradle Groovy or Maven instead).

First, we’ll start with plugins block:

Java

plugins {
    java
    war
    id("org.springframework.boot") version "3.3.2"
    id("io.spring.dependency-management") version "1.1.4"
}

Dependencies block:

Java

dependencies {
    //lombok
    compileOnly("org.projectlombok:lombok:1.18.32")
    annotationProcessor("org.projectlombok:lombok:1.18.32")
    testCompileOnly("org.projectlombok:lombok:1.18.32")
    testAnnotationProcessor("org.projectlombok:lombok:1.18.32")
    //springboot
 implementation("org.springframework.boot:spring-boot-starter-websocket:3.3.2")
    implementation("org.springframework.boot:spring-boot-starter-web:3.3.2")
    implementation("org.springframework.graphql:spring-graphql:1.3.2")
   providedRuntime("org.springframework.boot:spring-boot-starter-tomcat:3.3.2")
    //graphql
    implementation("com.graphql-java:graphql-java:22.2")
   implementation("org.springframework.boot:spring-boot-starter-graphql:3.3.2")

    //gson
    implementation("com.google.code.gson:gson:2.10.1")
    //jetbrains annotations
    implementation("org.jetbrains:annotations:23.0.0")
}

Defining a GraphQL Schema

When using GraphQL, you’ll need to define a schema where you’ll be defining types for your backend before you bind them to a controller in your SpringBoot app.

In the resources folder of your SpringBoot Java application, create a folder called “graphql”. After that, go ahead and create a file called “schema.graphqls”, this is where you’ll be defining data structures that GraphQL can understand. It should look like this:

After defining the schema file, we’ll be using this example of a schema that we’ll be using for our GraphQL tutorial:

Graphql

After defining the schema file, we’ll be using this example of a schema that we’ll be using for our GraphQL tutorial:

Java:

type Query {
    hello(name: String): String
    bookById(id: ID): Book
}

type Mutation {
    addAuthor(input: AuthorInput): Author
    addBook(input: BookInput): Book
}

input BookInput {
    title: String
    authorId: String
}

type Book {
    id: ID
    name: String
    pageCount: Int
    author: Author
}

input AuthorInput {
    firstName: String
    lastName: String
}

type Author {
    id: ID
    firstName: String
    lastName: String
}

Structure of a GraphQL Schema

This is where you’ll be defining your objects, queries, and mutations.

In the example schema above, we defined 4 different kinds of types:

Type Query - GraphQL reserves this type for you so you can define your queries here

Type Mutation - GraphQL reserves this type for you so you can define your mutations (write to database) here.

Type Book - Here we’re defining the structure of what Book will have. You can also reference other objects defined in this schema as a variable to another object as seen in Book.author

.Input BookInput - You’ll want to write an input for your Object if you don’t want to expose all the fields in your Object, such as the id field defined in Book. The frontend will be using this.

Defining the objects in Java

Now that we have our GraphQL schema defined with our objects, let’s define their Java counterparts:

Author:

Java

@Getter
@AllArgsConstructor
public class Author {
    private final String id;
    private final String firstName;
    private final String lastName;
}

AuthorInput:

java:

@Getter
@AllArgsConstructor
public class AuthorInput {
    private String firstName;
    private String lastName;
}

Book:

java

@Getter
@AllArgsConstructor
public class Book {
    private final String id;
    private final String name;
    private final int pageCount;
    private final String authorId;
}

BookInput:

java

@Getter
@AllArgsConstructor
public class BookInput {
    private String title;
    private String authorId;
}

Defining Repositories

We’ll be defining some simple classes that are meant to represent calling a database:

AuthorRepository

public class AuthorRepository {
    private static List<Author> authors = Arrays.asList(
            new Author("author-1", "Joanne", "Rowling"),
            new Author("author-2", "Herman", "Melville"),
            new Author("author-3", "Anne", "Rice")
    );

    public static Author getById(String id) {
        return authors.stream().filter(author -> 
author.getId().equals(id)).findFirst().orElse(null);
    }

    public static Author addAuthor(AuthorInput author)
    {
        Author authorToReturn = new Author("author-" + authors.size() + 1, 
author.getFirstName(), author.getLastName());
        authors.add(authorToReturn);
        return authorToReturn;
    }
}

Java

BookRepository

jave

public class BookRepository {
    private static List<Book> books = Arrays.asList(
       new Book("book-1", "Harry Potter and the Philosopher's 
Stone", 223, "author-1"),
       new Book("book-2", "Moby Dick", 635, "author-2"),
       new Book("book-3", "Interview with the vampire", 371, "author-3")
    );

    public static Book getById(String id) {
        return books.stream().filter(book -> 
book.getId().equals(id)).findFirst().orElse(null);
    }

    public static Book addBook(BookInput book)
    {
        Book bookToReturn = new Book("book-" + 
books.size() + 1, book.getTitle(), 0, book.getAuthorId());
        books.add(bookToReturn);
        return bookToReturn;
    }
}

Defining a Controller

We’re now at the stage where we connect everything together with a controller. We’ll now define a Spring Boot controller as shown below:

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.SchemaMapping;
import org.springframework.stereotype.Controller;



@Controller
class BookController {

    @QueryMapping
    public String hello(@Argument String name)
    {
        return "Hello, " + name + "!";
    }

    @QueryMapping
    public Book bookById(@Argument String id) {
        return BookRepository.getById(id);
    }

    @SchemaMapping
    public Author author(Book book) {
        return AuthorRepository.getById(book.getAuthorId());
    }

    @MutationMapping
    public Author addAuthor(@Argument AuthorInput input)
    {
        return AuthorRepository.addAuthor(input);
    }

    @MutationMapping
    public Book addBook(@Argument BookInput input)
    {
        return BookRepository.addBook(input);
    }
}

Let’s explain some of the methods defined in the controller:

@QueryMapping String hello(String name) - This method will get mapped to the Query’s definition of hello(name: String): String (Scroll up and see our GraphQL Schema definition)
@SchemaMapping Author author(Book book) - This is essential because in our GraphQL schema, we defined the Book object to return an Author, but in the Java object it holds the author ID instead. So when a Book gets queried, it’ll use this method to resolve the Author that belongs to this Book.
@MutationMapping Author addAuthor(AuthorInput input) - This method will get mapped to the Mutation’s definition of addAuthor(input: AuthorInput): Author (Scroll up and see our GraphQL Schema definition)

Testing GraphQL Queries

It’s now time to test some GraphQL statements on our Spring Boot backend, but we still need a client where we can execute GraphQL statements on. For this tutorial, we’ll be exposing & using the built-in GraphiQL instance that comes with Spring Boot.

Exposing GraphiQL

In your SpringBoot entrypoint class, add:

Java:

@Configuration
    public class GraphiQlConfiguration {
        @Bean
        @Order(0)
        public RouterFunction<ServerResponse> graphiQlRouterFunction() {
            RouterFunctions.Builder builder = RouterFunctions.route();
            ClassPathResource graphiQlPage = 
new ClassPathResource("graphiql/index.html");
            GraphiQlHandler graphiQLHandler = 
new GraphiQlHandler("/graphql", "", graphiQlPage);
            builder = builder.GET("/graphiql", graphiQLHandler::handleRequest);
            return builder.build();
        }
    }

You can see more about this implementation Implementation Notes here.

After implementing that, run your Spring Boot application and visit : http://localhost:8080/graphiql

Sample Queries

Now that we have the GraphiQL instance opened in our browser, let’s test some GraphQL queries.

Hello Query:

jave:

query {
  hello(name:"John")
}

Response from Hello Query:

{
  "data": {
    "hello": "Hello, John!"
  }
}

BookByID Query:

query {
  bookById(id: "book-1") {
    id
    name
    pageCount
    author {
      id
      firstName
      lastName
    }
  }
}

Response from BookByID Query:

{
  "data": {
    "bookById": {
      "id": "book-1",
      "name": "Harry Potter and the Philosopher's Stone",
      "pageCount": 223,
      "author": {
        "id": "author-1",
        "firstName": "Joanne",
        "lastName": "Rowling"
      }
    }
  }
}

AddAuthor Mutation:

mutation {
  addAuthor(input: { firstName: "John", lastName: "Doe" }) {
    id,
    firstName,
    lastName
  }
}

Response from AddAuthorMutation:

{
  "data": {
    "addAuthor": {
      "id": "author-4",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}