Getting Started With GraphQL SPQR and Spring Boot

1. Introduction

GraphQL is a query and manipulation language for web APIs. One of the libraries that originated to make working with GraphQL more seamless is SPQR.

In this tutorial, we’ll learn the basics of GraphQL SPQR and see it in action in a simple Spring Boot project.

2. What Is GraphQL SPQR?

GraphQL is a well-known query language created by Facebook. At its core are schemas – files in which we define custom types and functions.

In the traditional approach, if we wanted to add GraphQL to our project, we would have to follow two steps. First, we’d have to add GraphQL schema files to the project. Secondly, we’d need to write respective Java POJOs representing each type from the schema. This means that we’d be maintaining the same information in two places: in the schema files and in the Java classes. Such an approach is error-prone and requires more effort in maintaining the project.

GraphQL Schema Publisher & Query Resolver, SPQR in short, originated in order to reduce the above problems – it simply generates GraphQL schemas from the annotated Java classes.

3. Introducing GraphQL SPQR with Spring Boot

To see SPQR in action, we’ll set up a simple service. We’re going to use GraphQL Spring Boot Starter and GraphQL SPQR.

3.1. Setup

Let’s start by adding the dependencies for SPQR and Spring Boot to our POM:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <scope>test</scope>
<dependency>
    <groupId>io.leangen.graphql</groupId>
    <artifactId>spqr</artifactId>
    <version>0.12.4</version>
</dependency>

3.2. Writing the Model Book Class

Now that we’ve added the necessary dependencies, let’s create a simple Book class:

public class Book {
    private Integer id;
    private String author;
    private String title;
}

As we can see above, it doesn’t include any SPQR annotations. This can be very useful if we don’t own the source code but would like to benefit from this library.

3.3. Writing the BookService

In order to manage the collection of books, let’s create an IBookService interface:

public interface IBookService {
    Book getBookWithTitle(String title);

    List<Book> getAllBooks();

    Book addBook(Book book);

    Book updateBook(Book book);

    boolean deleteBook(Book book);
}

Then, we’ll provide an implementation of our interface:

@Service
public class BookService implements IBookService {

    private static final Set<Book> BOOKS_DATA = initializeData();

    @Override
    public Book getBookWithTitle(String title) {
        return BOOKS_DATA.stream()
            .filter(book -> book.getTitle().equals(title))
            .findFirst()
            .orElse(null);
    }

    @Override
    public List<Book> getAllBooks() {
        return new ArrayList<>(BOOKS_DATA);
    }

    @Override
    public Book addBook(Book book) {
        BOOKS_DATA.add(book);
        return book;
    }

    @Override
    public Book updateBook(Book book) {
        BOOKS_DATA.removeIf(b -> Objects.equals(b.getId(), book.getId()));
        BOOKS_DATA.add(book);
        return book;
    }

    @Override
    public boolean deleteBook(Book book) {
        return BOOKS_DATA.remove(book);
    }

    private static Set<Book> initializeData() {
        Book book = new Book(1, "J. R. R. Tolkien", "The Lord of the Rings");
        Set<Book> books = new HashSet<>();
        books.add(book);
        return books;
    }
}

3.4. Exposing the Service with graphql-spqr

The only thing left is creating a resolver, which will expose GraphQL mutations and queries. To do that, we’ll use two important SPQR annotations – @GraphQLMutation and @GraphQLQuery:

@Service
public class BookResolver {

    @Autowired
    IBookService bookService;

    @GraphQLQuery(name = "getBookWithTitle")
    public Book getBookWithTitle(@GraphQLArgument(name = "title") String title) {
        return bookService.getBookWithTitle(title);
    }

    @GraphQLQuery(name = "getAllBooks", description = "Get all books")
    public List<Book> getAllBooks() {
        return bookService.getAllBooks();
    }

    @GraphQLMutation(name = "addBook")
    public Book addBook(@GraphQLArgument(name = "newBook") Book book) {
        return bookService.addBook(book);
    }

    @GraphQLMutation(name = "updateBook")
    public Book updateBook(@GraphQLArgument(name = "modifiedBook") Book book) {
        return bookService.updateBook(book);
    }

    @GraphQLMutation(name = "deleteBook")
    public void deleteBook(@GraphQLArgument(name = "book") Book book) {
        bookService.deleteBook(book);
    }
}

If we don’t want to write @GraphQLArgument in every method and are satisfied with GraphQL parameters being named as the input parameters, we can compile the code with the -parameters argument.

3.5. Rest Controller

Finally, we’ll define a Spring @RestController. In order to expose the service with SPQR, we’ll configure the GraphQLSchema and GraphQL objects:

@RestController
public class GraphqlController {

    private final GraphQL graphQL;

    @Autowired
    public GraphqlController(BookResolver bookResolver) {
        GraphQLSchema schema = new GraphQLSchemaGenerator()
          .withBasePackages("com.baeldung")
          .withOperationsFromSingleton(bookResolver)
          .generate();
        this.graphQL = new GraphQL.Builder(schema)
          .build();
    }

It’s important to note that we have to register our BookResolver as a singleton.

The last task in our journey with SPQR is creating a /graphql endpoint. It’ll serve as a single point of contact with our service and will execute requested queries and mutations:

@PostMapping(value = "/graphql")
    public Map<String, Object> execute(@RequestBody Map<String, String> request, HttpServletRequest raw)
      throws GraphQLException {
        ExecutionResult result = graphQL.execute(request.get("query"));
        return result.getData();
    }
}

3.6. Result

We can check the results by inspecting the /graphql endpoint. For example, let’s retrieve all of the Book records by executing the following cURL command:

curl -g \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query":"{getAllBooks {id author title }}"}' \
  http://localhost:8080/graphql

3.7. Test

Once we’re done with the configuration, we can test our project. We’ll use @SpringBootTest to test our new endpoint and validate the responses. Let’s define the JUnit test and autowire the required WebTestClient:

@SpringBootTest(webEnvironment = RANDOM_PORT, classes = SpqrApp.class)
class SpqrAppIntegrationTest {

    private static final String GRAPHQL_PATH = "/graphql";

    @Autowired
    private WebTestClient webTestClient;

    @Test
    void whenGetAllBooks_thenValidResponseReturned() {
        String getAllBooksQuery = "{getAllBooks{ id title author }}";

        webTestClient.post()
          .uri(GRAPHQL_PATH)
          .contentType(MediaType.APPLICATION_JSON)
          .body(Mono.just(toJSON(getAllBooksQuery)), String.class)
          .exchange()
          .expectStatus().isOk()
          .expectBody()
          .jsonPath("$.getAllBooks").isNotEmpty();
    }

    @Test
    void whenAddBook_thenValidResponseReturned() {
        String addBookMutation = "mutation { addBook(newBook: {id: 123, author: \"J. K. Rowling\", "
          + "title: \"Harry Potter and Philosopher's Stone\"}) { id author title } }";

        webTestClient.post()
          .uri(GRAPHQL_PATH)
          .contentType(MediaType.APPLICATION_JSON)
          .body(Mono.just(toJSON(addBookMutation)), String.class)
          .exchange()
          .expectStatus().isOk()
          .expectBody()
          .jsonPath("$.addBook.id").isEqualTo("123")
          .jsonPath("$.addBook.title").isEqualTo("Harry Potter and Philosopher's Stone")
          .jsonPath("$.addBook.author").isEqualTo("J. K. Rowling");
    }

    private static String toJSON(String query) {
        try {
            return new JSONObject().put("query", query).toString();
        } catch (JSONException e) {
            throw new RuntimeException(e);
        }
    }

}

4. Using GraphQL SPQR Spring Boot Starter

The team working on SPQR has created a Spring Boot starter, which makes using it even easier. Let’s check it out!

4.1. Setup

We’ll start with adding the spqr-spring-boot-starter to our POM:

<dependency>
    <groupId>io.leangen.graphql</groupId>
    <artifactId>graphql-spqr-spring-boot-starter</artifactId>
    <version>1.0.1</version>
</dependency>

4.2. BookService

Then, we need to add two modifications to our BookService. First of all, it has to be annotated with the @GraphQLApi annotation. In addition, every method we’d like to expose in our API has to have a respective annotation:

@Service
@GraphQLApi
public class BookService implements IBookService {

    private static final Set<Book> BOOKS_DATA = initializeData();

    @GraphQLQuery(name = "getBookWithTitle")
    public Book getBookWithTitle(@GraphQLArgument(name = "title") String title) {
        return BOOKS_DATA.stream()
            .filter(book -> book.getTitle().equals(title))
            .findFirst()
            .orElse(null);
    }

    @GraphQLQuery(name = "getAllBooks", description = "Get all books")
    public List<Book> getAllBooks() {
        return new ArrayList<>(BOOKS_DATA);
    }

    @GraphQLMutation(name = "addBook")
    public Book addBook(@GraphQLArgument(name = "newBook") Book book) {
        BOOKS_DATA.add(book);
        return book;
    }

    @GraphQLMutation(name = "updateBook")
    public Book updateBook(@GraphQLArgument(name = "modifiedBook") Book book) {
        BOOKS_DATA.removeIf(b -> Objects.equals(b.getId(), book.getId()));
        BOOKS_DATA.add(book);
        return book;
    }

    @GraphQLMutation(name = "deleteBook")
    public boolean deleteBook(@GraphQLArgument(name = "book") Book book) {
        return BOOKS_DATA.remove(book);
    }

    private static Set<Book> initializeData() {
        Book book = new Book(1, "J. R. R. Tolkein", "The Lord of the Rings");
        Set<Book> books = new HashSet<>();
        books.add(book);
        return books;
    }

}

As we can see, we basically moved the code from the BookResolver to the BookService. Additionally, we don’t need the GraphqlController class – a /graphql endpoint will be added automatically.

5. Summary

GraphQL is an exciting framework and an alternative to traditional RESTful endpoints. While offering a lot of flexibility, it can also add some tedious tasks such as maintaining schema files. SPQR aspires to make working with GraphQL easier and less error-prone.

In this article, we saw how to add SPQR to the existing POJOs and configure it to serve queries and mutations. Then, we saw a new endpoint in action in GraphQL. Lastly, we verified our application’s behavior using Spring’s testing support.