GraphQL is a query language for APIs and a runtime for executing those queries by providing a more efficient, powerful, and flexible alternative to REST APIs. It allows clients to request only the data they need, reducing over-fetching and under-fetching of data. With GraphQL, you can query multiple resources in a single request and have the flexibility to specify exactly what fields to return.
In this guide, we will explore how to develop a GraphQL API using Java with frameworks like GraphQL Java and Spring Boot.
1. Introduction to GraphQL
GraphQL is a specification developed by Facebook that enables clients to request exactly the data they need. Unlike REST APIs, where you might have to make multiple requests to different endpoints to get the required data, GraphQL lets you query multiple endpoints in a single request.
Key Features of GraphQL:
- Declarative Data Fetching: Clients define the structure of the response they need.
- Single Request: Multiple resources can be fetched in a single query.
- Strongly Typed: The schema defines the types of data and their relationships.
- Real-time Data: Support for subscriptions for real-time updates.
2. Setting Up a Java GraphQL API
To build a GraphQL API in Java, you can use libraries like GraphQL Java or frameworks like Spring Boot with GraphQL. In this example, we will use Spring Boot along with GraphQL Java to create a simple GraphQL API.
2.1. Maven Setup
Add the following dependencies to your pom.xml to set up Spring Boot and GraphQL:
<dependencies>
<!-- Spring Boot Starter Web (for REST and general web functionality) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Spring Boot Starter GraphQL -->
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java</artifactId>
<version>17.3</version> <!-- Use the latest version -->
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</dependency>
<!-- GraphQL Spring Boot Starter -->
<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-spring-boot-starter</artifactId>
<version>11.1</version> <!-- Use the latest version -->
</dependency>
</dependencies>
Additionally, you will need to configure GraphQL with Spring Boot by adding the necessary properties in application.properties:
# Enable GraphQL endpoints
graphql.servlet.mapping=/graphql
graphql.servlet.enabled=true
graphql.servlet.corsEnabled=true
3. Define the GraphQL Schema
A GraphQL schema defines the structure of the API, including the queries and types. The schema is written in a special GraphQL schema definition language (SDL).
3.1. GraphQL Schema Definition (schema.graphqls)
Create a file called schema.graphqls under the src/main/resources directory to define your GraphQL schema. Here is an example schema for a simple query:
type Query {
getBooks: [Book]
getBookById(id: ID!): Book
}
type Book {
id: ID
title: String
author: String
publishedYear: Int
}
In this schema:
- The
Querytype defines two queries:getBooks(returns a list of books) andgetBookById(returns a single book by itsID). - The
Booktype defines fields for a book, includingid,title,author, andpublishedYear.
4. Implement GraphQL Resolvers
GraphQL resolvers are responsible for fetching the data for each query in the schema. In Spring Boot, these are typically implemented as simple Java classes with methods that correspond to the fields in the GraphQL schema.
4.1. Create the Book Model
First, create a simple Java class to represent the Book model:
public class Book {
private String id;
private String title;
private String author;
private int publishedYear;
// Constructors, getters, and setters
}
4.2. Create the GraphQL Resolver
Next, implement the resolver class that will handle the getBooks and getBookById queries:
import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.ArrayList;
import java.util.Optional;
@Component
public class BookQueryResolver implements GraphQLQueryResolver {
private List<Book> books = new ArrayList<>();
// Constructor to add some sample data
public BookQueryResolver() {
books.add(new Book("1", "The Catcher in the Rye", "J.D. Salinger", 1951));
books.add(new Book("2", "To Kill a Mockingbird", "Harper Lee", 1960));
books.add(new Book("3", "1984", "George Orwell", 1949));
}
// Resolver for getting all books
public List<Book> getBooks() {
return books;
}
// Resolver for getting a book by its ID
public Book getBookById(String id) {
Optional<Book> book = books.stream().filter(b -> b.getId().equals(id)).findFirst();
return book.orElse(null);
}
}
In this code:
- The
BookQueryResolverclass implements theGraphQLQueryResolverinterface, which is provided by GraphQL Java Tools to map GraphQL queries to Java methods. getBooks()returns the list of books, andgetBookById()returns a book by itsid.
5. Set Up the Spring Boot Application
Now, let’s set up the main Spring Boot application class to run the GraphQL API.
5.1. Spring Boot Application
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class GraphQLApplication {
public static void main(String[] args) {
SpringApplication.run(GraphQLApplication.class, args);
}
}
This class initializes the Spring Boot application.
6. Querying the GraphQL API
Once the application is up and running, you can query the GraphQL API at the /graphql endpoint. For example, use Postman or GraphiQL (a popular GraphQL IDE) to interact with the API.
Here is an example of a GraphQL query:
query {
getBooks {
id
title
author
publishedYear
}
}
Response:
{
"data": {
"getBooks": [
{
"id": "1",
"title": "The Catcher in the Rye",
"author": "J.D. Salinger",
"publishedYear": 1951
},
{
"id": "2",
"title": "To Kill a Mockingbird",
"author": "Harper Lee",
"publishedYear": 1960
},
{
"id": "3",
"title": "1984",
"author": "George Orwell",
"publishedYear": 1949
}
]
}
}
7. Advantages of GraphQL in Java Development
- Efficient Data Fetching: GraphQL allows clients to fetch only the data they need, improving performance.
- Single Request: Multiple resources can be fetched in a single request.
- Real-time Updates: With subscriptions, clients can receive real-time updates for data changes.
- Flexible Schema: GraphQL provides a flexible schema that can evolve without affecting the client-side code.