For years, REST APIs have been the standard for building backend services in Java. They’re simple, well-understood, and widely adopted. But as applications grow, REST’s rigid structure can lead to over-fetching or under-fetching data, making clients request more or less than they actually need.
This is where GraphQL comes in—a query language and runtime for APIs that gives clients the flexibility to request exactly the data they need. In this article, we’ll explore how GraphQL works in Java, compare it to REST, and walk through practical examples.
1. Why Move Beyond REST?
REST Example
A client requesting a user profile might need both user details and their posts:
GET /users/1 GET /users/1/posts
This requires two network calls. REST often forces clients to fetch multiple endpoints or download unnecessary data.
GraphQL Example
With GraphQL, the same request could be written as:
{
user(id: 1) {
name
email
posts {
title
content
}
}
}
👉 One request, one endpoint, tailored response.
2. Setting Up GraphQL in Java
The Java ecosystem has strong GraphQL libraries, such as:
- graphql-java → Low-level GraphQL implementation for Java
- Spring Boot + GraphQL → Integrates GraphQL with Spring Boot, offering schema-first or annotation-based development
Example: Spring Boot GraphQL Setup
Maven dependency:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-graphql</artifactId> </dependency>
GraphQL schema (schema.graphqls):
type Query {
user(id: ID!): User
}
type User {
id: ID!
name: String
email: String
posts: [Post]
}
type Post {
id: ID!
title: String
content: String
}
Resolver in Java:
@Component
public class UserResolver implements GraphQLQueryResolver {
public User getUser(Long id) {
return new User(id, "Alice", "alice@example.com",
List.of(new Post(1L, "Hello GraphQL", "GraphQL is powerful!"))
);
}
}
Query Example:
{
user(id: 1) {
name
posts {
title
}
}
}
Response:
{
"data": {
"user": {
"name": "Alice",
"posts": [
{ "title": "Hello GraphQL" }
]
}
}
}
3. REST vs GraphQL: Key Differences
| Feature | REST | GraphQL |
|---|---|---|
| Data Fetching | Fixed endpoints | Flexible queries (client-defined) |
| Over-fetching | Common | Avoided (fetch only what’s needed) |
| Under-fetching | Common (multiple calls) | Solved with nested queries |
| Versioning | Often needed (/v1, /v2) | Evolving schema, no versioning |
| Performance | Multiple network calls | One endpoint, fewer calls |
| Learning Curve | Low | Higher (schema, resolvers) |
4. Best Practices for GraphQL in Java
- Use schema-first design → Define
schema.graphqlsand build resolvers around it. - Batch requests with DataLoader → Prevent N+1 query issues in GraphQL.
- Add GraphQL Playground / Voyager → For interactive query testing.
- Secure your API → Restrict expensive queries with query cost analysis or depth limits.
5. When to Use GraphQL over REST?
✅ Choose GraphQL if:
- Your clients (mobile, web, IoT) need different slices of data.
- You want to reduce round trips for complex data fetching.
- You’re building modern, data-rich applications (e.g., dashboards, social apps).
❌ Stick with REST if:
- Your API is simple with predictable endpoints.
- You prioritize caching via HTTP/CDN.
- You don’t want the learning overhead of GraphQL.
Final Thoughts
GraphQL doesn’t replace REST entirely—it complements it. REST is still a solid choice for simple APIs and microservices. But if your application demands flexibility, efficiency, and a better developer experience, moving beyond REST to GraphQL in Java is a smart decision.
Useful Links
