GraphQL API with Java: Step-by-Step Tutorial for Beginners

Introduction to GraphQL API with Java

GraphQL is a query language for APIs that allows clients to request only the data they actually need. Unlike REST, where each endpoint returns a fixed data structure, GraphQL provides flexibility and reduces the number of requests. In this tutorial, we will create a full GraphQL API in Java using Spring Boot and the graphql-java library. You will learn how to set up the project, define the schema, write resolvers, and handle queries and mutations. All code examples are ready to run.

1. Project Setup and Dependencies

First, let's create a new Spring Boot project. We will use Maven, but you can adapt the example for Gradle. Add the following dependencies to pom.xml:

<dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-web</artifactId></dependency><dependency>    <groupId>com.graphql-java</groupId>    <artifactId>graphql-java</artifactId>    <version>21.0</version></dependency><dependency>    <groupId>com.graphql-java</groupId>    <artifactId>graphql-java-spring-boot-starter-webmvc</artifactId>    <version>2021-06-28T00-00-00-6e3b7b2</version></dependency>

After adding the dependencies, create the main application class:

@SpringBootApplicationpublic class GraphqlApplication {    public static void main(String[] args) {        SpringApplication.run(GraphqlApplication.class, args);    }}

Now let's configure the GraphQL entry point. Create a file application.yml in the resources folder:

graphql:  servlet:    mapping: /graphql    enabled: true    cors-enabled: true

Done! The basic project structure is up and running. Next, we move on to defining the schema.

2. Defining the GraphQL Schema

The schema is the core of a GraphQL API. It describes data types, queries, and mutations. Let's create a file schema.graphqls in the src/main/resources folder:

type Book {    id: ID!    title: String!    author: String!    year: Int}

type Query {    books: [Book]    bookById(id: ID!): Book}

type Mutation {    addBook(title: String!, author: String!, year: Int): Book    deleteBook(id: ID!): Boolean}

Here we defined:

• Book — an object with fields id, title, author, and year.
• Query — entry points for reading data (list of books and search by ID).
• Mutation — data modification operations (adding and deleting a book).

Now we need to load this schema into the application. Let's create a configuration class:

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import graphql.GraphQL;import graphql.schema.GraphQLSchema;import graphql.schema.idl.RuntimeWiring;import graphql.schema.idl.SchemaGenerator;import graphql.schema.idl.SchemaParser;import graphql.schema.idl.TypeDefinitionRegistry;

import java.io.File;import java.io.IOException;

@Configurationpublic class GraphqlConfig {

    @Bean    public GraphQL graphQL() throws IOException {        File schemaFile = new File("src/main/resources/schema.graphqls");        TypeDefinitionRegistry typeRegistry = new SchemaParser().parse(schemaFile);        RuntimeWiring wiring = buildWiring();        GraphQLSchema schema = new SchemaGenerator().makeExecutableSchema(typeRegistry, wiring);        return GraphQL.newGraphQL(schema).build();    }

    private RuntimeWiring buildWiring() {        return RuntimeWiring.newRuntimeWiring()                .type(