Designing Scalable Java APIs With GraphQL

Have you ever wondered if there’s a better way to fetch data for your applications than REST APIs? In back-end development, GraphQL has emerged as a powerful alternative, offering a more flexible and efficient approach to data fetching. For developers familiar with Java, integrating GraphQL into a modern backend opens the door to scalable and high-performing APIs tailored for a wide range of use cases.

This blog will explore the key differences between GraphQL and REST, highlight the unique benefits of using GraphQL for data fetching, and guide you through implementing a GraphQL API in Java with a real-world example.

What Is GraphQL?

GraphQL is a query language for APIs and a runtime for executing those queries. Unlike REST, where fixed endpoints return predefined data, GraphQL allows clients to request exactly the data they need. This granularity makes GraphQL highly efficient, particularly for complex or data-intensive applications.

Advantages of the GraphQL Approach:

• Granular Data Fetching: The client can query only name and designation without retrieving unnecessary fields like department.
• Nested Queries: Fetch the manager details along with employee information in a single query.
• Schema-Driven Development: The schema acts as a contract, making API evolution easier.

What Is REST API?

Representational State Transfer (REST) is an architectural style for building APIs. It uses standard HTTP methods like GET, POST, PUT, and DELETE to perform CRUD operations. REST is known for its simplicity and widespread adoption.

Limitations of REST:

• Over-fetching or under-fetching of data.
• Requires multiple endpoints and versioning to accommodate changes.
• No built-in real-time capabilities.

GraphQL vs. REST API: What’s the Difference?

GraphQL and REST are two popular approaches for building APIs, each with its strengths. While REST has been the standard for years, GraphQL offers more flexibility and efficiency, particularly in data retrieval and collaboration between front-end and back-end teams.

Key Differences

• Unlike REST, which uses multiple endpoints and requires versioning for changes, GraphQL consolidates data retrieval into a single query and reduces the need for versioning as clients specify data requirements. 
• While REST uses HTTP status codes to indicate success or errors, GraphQL always returns a 200 OK status and communicates errors in the response body. 
• GraphQL also supports real-time updates through subscriptions, unlike REST, which lacks built-in real-time support. 
• Though REST is widely established with many tools, GraphQL’s environment has grown rapidly, offering powerful tools like GraphiQL for easier development. 
• Lastly, while REST uses headers for caching, GraphQL requires more advanced techniques due to dynamic queries but offers options like persisted queries for efficient caching.

Core GraphQL Concepts

1. Schema Definition Language (SDL)

GraphQL has its own type system that is used to define the schema of an API. The syntax for writing schemas is called Schema Definition Language (SDL).

2. Queries vs. Mutations vs. Subscriptions

• Queries are used to fetch data from the server. Unlike REST, which uses multiple fixed endpoints, GraphQL uses a single endpoint, and the client specifies the data needed in the query, offering flexibility.
• Mutations are used to modify data on the server, such as creating, updating, or deleting data. They allow clients to send changes to the backend and are essential for applications that need to write data.
• Subscriptions enable real-time updates by maintaining a steady connection between the client and the server. When a subscribed event occurs, the server pushes updates to the client, providing continuous data streams, unlike queries and mutations, which follow a request-response cycle.

3. GraphQL Schema

It defines the data structure that can be queried or mutated, acting as a contract between the server and the client. It specifies the types, fields, and relationships available for clients to access. The schema typically includes special root types: Query for data retrieval, Mutation for modifying data, and Subscription for real-time updates. These types collectively define the API's capabilities and how clients can interact with it.

4. Resolvers: Mapping GraphQL Queries to Data

Resolvers are functions that handle the logic for fetching data in a GraphQL server. Each field in a schema is linked to a resolver, which determines how to retrieve or compute the data for that field. When a query is executed, the server invokes the appropriate resolvers for the requested fields. Resolvers can return scalars or objects, with execution continuing for child fields if an object is returned and completing if a scalar is returned. If null is returned, execution stops. Resolvers are essential for mapping GraphQL queries to the actual data sources.

Benefits of Using GraphQL in Java

1. Exact Data Fetching: Query only the data you need, nothing more, ensuring predictable and efficient results.
2. Single Request for Multiple Resources: Fetch related data in one query, reducing multiple API calls.
3. Type System: Organises APIs by types and fields, ensuring queries are valid and errors are clear.
4. Developer Tools: Enhance productivity with tools like GraphiQL, using type definitions for better query building and debugging.
5. Versionless Evolution: Add or deprecate fields without breaking existing queries, keeping APIs maintainable.
6. Flexible Data Integration: Create a unified API over existing data and code that is compatible with various storage engines and languages.

Setting Up a GraphQL API in Java

Real-World Example: Users and Orders

Imagine you are building an Employee Directory API for a large organization. The goal is to allow clients to query details like employee name, designation, department, and even their reporting hierarchy.

1. Set Up the Project

Create a new Spring Boot project using Spring Tool Suite or going to Spring Initialiser. Then, add these dependencies to pom.xml file:

<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-graphql</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>com.mysql</groupId>
			<artifactId>mysql-connector-j</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-webflux</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.graphql</groupId>
			<artifactId>spring-graphql-test</artifactId>
			<scope>test</scope>
		
		</dependency>
		
	</dependencies>

2. Create Your Entities

Create Java entities (e.g., User and Order) to represent the data that will be queried or mutated via GraphQL. For example:

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long userId;
    private String name;
    private String email;
    private String password;
    // Getters and setters...
}

@Entity
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long orderId;
    private String orderDetails;
    private String address;
    private int price;
    @ManyToOne
    private User user;
    // Getters and setters...
}

3. Create Repositories

Create repositories to interact with the database:

@Repository
public interface UserRepository extends JpaRepository<User, Long> {}

@Repository
public interface OrderRepository extends JpaRepository<Order, Long> {}

4. Create Service Classes

Create service classes to handle business logic:

@Service
public class UserService {
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public User createUser(User user) {
        return userRepository.save(user);
    }

    public User getUser(Long userId) {
        return userRepository.findById(userId).orElseThrow(() -> new RuntimeException("User not found"));
    }

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    public boolean deleteUser(Long userId) {
        userRepository.deleteById(userId);
        return true;
    }
}

5. Create GraphQL Controllers

Define GraphQL controllers to handle queries and mutations:

@Controller
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @QueryMapping
    public List<User> getUsers() {
        return userService.getAllUsers();
    }

    @QueryMapping
    public User getUser(@Argument Long userId) {
        return userService.getUser(userId);
    }

    @MutationMapping
    public User createUser(@Argument String name, @Argument String email, @Argument String password) {
        User user = new User();
        user.setName(name);
        user.setEmail(email);
        user.setPassword(password);
        return userService.createUser(user);
    }

    @MutationMapping
    public boolean deleteUser(@Argument Long userId) {
        return userService.deleteUser(userId);
    }
}

6. Define Your GraphQL Schema

Create a schema.graphqls file in the src/main/resources directory:

type User {
    userId: ID!
    name: String
    email: String
    password: String
}

type Query {
    getUsers: [User]
    getUser(userId: ID!): User
}

type Mutation {
    createUser(name: String, email: String, password: String): User
    deleteUser(userId: ID!): Boolean
}

7. Configure GraphQL in application.properties

Optionally, configure GraphQL settings in scr/main/resources/application.properties:

spring.graphql.graphiql.enabled=true

8. Run Your Application

Run the SpringBoot application using mvn spring-boot:run or from your IDE. Once running, you can access the GraphAL endpoint at /graphiql.

9. Test With GraphQL Queries

Test the GraphQL API using a tool like GraphiQL or Postman.

For Mutation: 

mutation {
  createUser(
    name:"swetha",
    email:"swethadutta@gmail.com",
    password:"23sde4dfg43"
  ){
    name,
    userId
  }
}

Output:

{
  "data": {
    "createUser": {
      "name": "swetha",
      "userId": "3"
    }
  }
}

For Query:

query{
  getUsers{
    name
  }

}

Output:

{
  "data": {
    "getUsers": [
      {
        "name": "Medha"
      },
      {
        "name": "Riya"
      },
      {
        "name": "swetha"
      }
    ]
  }
}

Advanced GraphQL Features

1. Enhancing Reusability With Fragments

A fragment is basically a reusable set of fields defined for a specific type. It is a feature that helps improve the structure and reusability of your GraphQL code.

2. Parameterizing Fields With Arguments

In GraphQL, fields can accept arguments to make queries more dynamic and flexible. These arguments allow you to filter or customize the data returned by the API.

3. Paginating and Sorting With GraphQL

Pagination

Pagination is a tricky topic in API design. On a high level, there are two major approaches regarding how it can be tackled.

• Limit-offset: Request a specific chunk of the list by providing the indices of the items to be retrieved (in fact, you’re mostly providing the start index (offset) as well as a count of items to be retrieved (limit)).
• Cursor-based: This pagination model is a bit more advanced. Every element in the list is associated with a unique ID (the cursor). Clients paginating through the list then provide the cursor of the starting element as well as a count of items to be retrieved.

Sorting

With Graphql API Design, it is possible to return lists of elements that are sorted (ordered) according to specific criteria.

Challenges and Considerations of Using GraphQL

• Complexity: Managing GraphQL schemas and queries can be challenging for simple data models or inexperienced teams.
• Performance Issues: Deeply nested queries can strain backend resources if not optimized.
• Caching Challenges: Standard REST-based caching strategies don’t apply and require custom solutions.
• Security Concerns: Over-fetching and malicious queries necessitate query limits and other safeguards.
• Hybrid Usage: Works best for complex data needs, often combined with REST for simpler operations.

Conclusion

GraphQL offers a flexible and efficient approach to building modern APIs in Java, making it an ideal choice for dynamic and data-intensive applications. Its single-endpoint architecture and strong typing simplify API design while ensuring robust performance. Whether you're creating a simple employee directory or a complex analytics platform, GraphQL empowers developers to deliver scalable solutions with ease. Start exploring GraphQL today with tools like Spring Boot and graphql-java to unlock its full potential in your next project.

Source Code

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