GraphQL in Java: 5 Powerful Frameworks for Building Modern APIs

As a best-selling author, I invite you to explore my books on Amazon. Don't forget to follow me on Medium and show your support. Thank you! Your support means the world!

GraphQL has revolutionized how we build APIs by offering an alternative to traditional REST approaches. As a Java developer who's implemented numerous GraphQL services, I've found it transforms how clients interact with our backend systems. Instead of navigating multiple endpoints, clients can request precisely the data they need through a single endpoint with strongly typed schemas.

When I first discovered GraphQL, I was skeptical about its benefits over REST. However, after implementing it in production systems, I've seen how it eliminates over-fetching and under-fetching of data while providing superior developer experience.

Let me walk you through the most effective Java frameworks for GraphQL implementation, with practical examples and insights from real-world usage.

Why GraphQL for Java Applications

GraphQL offers a query language for APIs that gives clients the power to request exactly what they need. This approach provides significant advantages:

Type safety throughout the entire stack ensures consistency between client requests and server responses. The schema acts as a contract that both sides understand.

A single endpoint simplifies API management compared to multiple REST endpoints for different resources and operations.

The self-documenting nature reduces the need for extensive API documentation and makes it easier for new developers to understand the available data and operations.

For Java applications specifically, GraphQL provides a natural fit with Java's strong typing system. The Java ecosystem offers several robust frameworks to implement GraphQL services.

Spring for GraphQL

Spring for GraphQL builds on the popular Spring framework, making it an excellent choice for developers already working within the Spring ecosystem. Released by the Spring team, it provides seamless integration with Spring Boot and other Spring components.

One of the framework's strengths is its annotation-based approach, which should feel familiar to Spring developers:

@Controller
public class BookController {
    private final BookRepository bookRepository;

    public BookController(BookRepository bookRepository) {
        this.bookRepository = bookRepository;
    }

    @QueryMapping
    public Book bookById(@Argument Long id) {
        return bookRepository.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
    }

    @QueryMapping
    public List<Book> books() {
        return bookRepository.findAll();
    }

    @MutationMapping
    public Book createBook(@Argument String title, @Argument String author, @Argument Integer pageCount) {
        Book book = new Book();
        book.setTitle(title);
        book.setAuthor(author);
        book.setPageCount(pageCount);
        return bookRepository.save(book);
    }
}

The corresponding schema file (schema.graphqls) would look like:

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

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

type Mutation {
    createBook(title: String!, author: String!, pageCount: Int): Book!
}

Setting up Spring for GraphQL with Spring Boot is straightforward with the appropriate dependencies:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-graphql'
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

Spring for GraphQL also excels in error handling:

@Controller
public class BookController {
    // Other methods omitted

    @ExceptionHandler(BookNotFoundException.class)
    public GraphQLError handleBookNotFoundException(BookNotFoundException ex) {
        return GraphQLError.newError()
            .errorType(ErrorType.NOT_FOUND)
            .message(ex.getMessage())
            .build();
    }
}

Netflix DGS Framework

The Netflix Domain Graph Service (DGS) framework is another powerful option built on top of GraphQL Java. Netflix created this framework to support their microservices architecture and federated GraphQL approach.

DGS shines in environments with multiple services contributing to a unified GraphQL schema:

@DgsComponent
public class BookDataFetcher {
    private final BookService bookService;

    public BookDataFetcher(BookService bookService) {
        this.bookService = bookService;
    }

    @DgsQuery
    public List<Book> books() {
        return bookService.getAllBooks();
    }

    @DgsQuery
    public Book bookById(@InputArgument String id) {
        return bookService.getBookById(id);
    }

    @DgsMutation
    public Book addBook(@InputArgument BookInput bookInput) {
        return bookService.createBook(
            bookInput.getTitle(),
            bookInput.getAuthor(),
            bookInput.getPageCount()
        );
    }

    @DgsData(parentType = "Book", field = "reviews")
    public List<Review> reviews(DgsDataFetchingEnvironment dfe) {
        Book book = dfe.getSource();
        return bookService.getReviewsForBook(book.getId());
    }
}

A key advantage of DGS is its code generation capabilities. Given a GraphQL schema, DGS can generate Java types that represent your domain:

./gradlew generateJava

This generates classes based on your schema, which you can reference in your data fetchers.

DGS also provides excellent testing utilities:

@SpringBootTest
public class BookDataFetcherTest {
    @Autowired
    DgsQueryExecutor dgsQueryExecutor;

    @MockBean
    BookService bookService;

    @Test
    void testGetBooks() {
        when(bookService.getAllBooks())
            .thenReturn(List.of(new Book("1", "Title", "Author", 100)));

        GraphQLResponse response = dgsQueryExecutor.executeAndExtractJsonPathAsObject(
            "{ books { id title author } }",
            "data.books[0]",
            Book.class
        );

        Book book = response.get();
        assertEquals("Title", book.getTitle());
    }
}

GraphQL Java

GraphQL Java is the foundation upon which many other Java GraphQL frameworks are built. It provides low-level control over how GraphQL schemas are defined and executed, making it suitable for custom implementations and integrations.

Here's how you might set up a basic GraphQL service using the raw GraphQL Java library:

public class GraphQLProvider {
    private GraphQL graphQL;
    private BookRepository bookRepository;

    @Autowired
    public GraphQLProvider(BookRepository bookRepository) {
        this.bookRepository = bookRepository;
    }

    @PostConstruct
    public void init() throws IOException {
        URL url = Resources.getResource("schema.graphqls");
        String sdl = Resources.toString(url, Charsets.UTF_8);
        GraphQLSchema graphQLSchema = buildSchema(sdl);
        this.graphQL = GraphQL.newGraphQL(graphQLSchema).build();
    }

    private GraphQLSchema buildSchema(String sdl) {
        TypeDefinitionRegistry typeRegistry = new SchemaParser().parse(sdl);
        RuntimeWiring runtimeWiring = buildWiring();
        SchemaGenerator schemaGenerator = new SchemaGenerator();
        return schemaGenerator.makeExecutableSchema(typeRegistry, runtimeWiring);
    }

    private RuntimeWiring buildWiring() {
        return RuntimeWiring.newRuntimeWiring()
            .type(TypeRuntimeWiring.newTypeWiring("Query")
                .dataFetcher("bookById", env -> {
                    String id = env.getArgument("id");
                    return bookRepository.findById(id).orElse(null);
                })
                .dataFetcher("books", env -> bookRepository.findAll())
            )
            .type(TypeRuntimeWiring.newTypeWiring("Mutation")
                .dataFetcher("createBook", env -> {
                    String title = env.getArgument("title");
                    String author = env.getArgument("author");
                    Integer pageCount = env.getArgument("pageCount");
                    Book book = new Book(null, title, author, pageCount);
                    return bookRepository.save(book);
                })
            )
            .build();
    }

    @Bean
    public GraphQL graphQL() {
        return graphQL;
    }
}

While this approach requires more code than annotation-based frameworks, it provides complete control over GraphQL execution.

Apollo Federation for Java

Apollo Federation enables you to build a unified GraphQL schema from multiple services, each responsible for a portion of the graph. This approach is particularly valuable in microservices architectures.

To implement a federated service in Java, you can use the federation-jvm library:

public class BookService {
    @Component
    public static class BookGraphQLQueryResolver implements GraphQLQueryResolver {
        private final BookRepository bookRepository;

        public BookGraphQLQueryResolver(BookRepository bookRepository) {
            this.bookRepository = bookRepository;
        }

        public Book bookById(String id) {
            return bookRepository.findById(id).orElse(null);
        }

        public List<Book> books() {
            return bookRepository.findAll();
        }
    }

    @Component
    public static class BookGraphQLResolver implements GraphQLResolver<Book> {
        private final ReviewRepository reviewRepository;

        public BookGraphQLResolver(ReviewRepository reviewRepository) {
            this.reviewRepository = reviewRepository;
        }

        public List<Review> reviews(Book book) {
            return reviewRepository.findByBookId(book.getId());
        }
    }
}

The federated schema would include directives to specify entity resolution:

type Book @key(fields: "id") {
    id: ID!
    title: String!
    author: String!
    pageCount: Int
    reviews: [Review!]
}

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

With this setup, other services can reference books by ID, and the federation gateway will resolve these references through the Book service.

MicroProfile GraphQL

For Java EE and Jakarta EE applications, MicroProfile GraphQL provides a standard API for GraphQL services. It's particularly well-suited for enterprise applications and integrates naturally with other MicroProfile specifications.

MicroProfile GraphQL uses annotations to define the schema:

@GraphQLApi
public class BookResource {
    @Inject
    BookRepository bookRepository;

    @Query("bookById")
    public Book getBook(@Name("id") String id) {
        return bookRepository.findById(id).orElse(null);
    }

    @Query
    public List<Book> allBooks() {
        return bookRepository.findAll();
    }

    @Mutation
    public Book createBook(BookInput bookInput) {
        Book book = new Book();
        book.setTitle(bookInput.getTitle());
        book.setAuthor(bookInput.getAuthor());
        book.setPageCount(bookInput.getPageCount());
        return bookRepository.save(book);
    }
}

@GraphQLApi
public class ReviewResource {
    @Inject
    ReviewRepository reviewRepository;

    @Query
    public List<Review> reviewsForBook(@Name("bookId") String bookId) {
        return reviewRepository.findByBookId(bookId);
    }
}

The corresponding entity classes would use the @Type annotation:

@Type
public class Book {
    @Id
    private String id;

    @NonNull
    private String title;

    @NonNull
    private String author;

    private Integer pageCount;

    // Getters and setters
}

@InputType
public class BookInput {
    @NonNull
    private String title;

    @NonNull
    private String author;

    private Integer pageCount;

    // Getters and setters
}

Practical Considerations for GraphQL in Java

After implementing GraphQL in multiple Java projects, I've encountered certain patterns and practices worth sharing:

Performance Optimization: N+1 query problems often arise in GraphQL when resolving nested relationships. DataLoader patterns can batch and cache requests:

@Component
public class ReviewDataLoader {
    private final ReviewRepository reviewRepository;
    private final BatchLoader<String, List<Review>> reviewBatchLoader;
    private final DataLoader<String, List<Review>> reviewDataLoader;

    public ReviewDataLoader(ReviewRepository reviewRepository) {
        this.reviewRepository = reviewRepository;
        this.reviewBatchLoader = bookIds -> CompletableFuture.supplyAsync(() -> {
            List<Review> allReviews = reviewRepository.findByBookIdIn(bookIds);
            Map<String, List<Review>> reviewsByBookId = allReviews.stream()
                .collect(Collectors.groupingBy(Review::getBookId));
            return bookIds.stream()
                .map(id -> reviewsByBookId.getOrDefault(id, Collections.emptyList()))
                .collect(Collectors.toList());
        });
        this.reviewDataLoader = DataLoader.newDataLoader(reviewBatchLoader);
    }

    public DataLoader<String, List<Review>> getReviewDataLoader() {
        return reviewDataLoader;
    }
}

Security Considerations: GraphQL presents unique security challenges. Implement depth limiting to prevent excessively complex queries:

GraphQL.newGraphQL(graphQLSchema)
    .executionStrategy(new AsyncExecutionStrategy())
    .instrumentation(new MaxQueryDepthInstrumentation(10))
    .build();

Pagination: For large collections, cursor-based pagination works well with GraphQL:

@QueryMapping
public BookConnection books(
        @Argument Integer first, 
        @Argument String after) {
    PageRequest page = CursorUtil.decodeCursor(after, first);
    Page<Book> bookPage = bookRepository.findAll(page);
    return BookConnection.fromPage(bookPage);
}

Error Handling: Provide detailed error information without exposing sensitive details:

@ExceptionHandler(ConstraintViolationException.class)
public GraphQLError handleConstraintViolation(ConstraintViolationException ex) {
    List<String> details = ex.getConstraintViolations().stream()
        .map(violation -> violation.getPropertyPath() + " " + violation.getMessage())
        .collect(Collectors.toList());

    return GraphQLError.newError()
        .errorType(ErrorType.VALIDATION_ERROR)
        .message("Validation error")
        .extensions(Collections.singletonMap("details", details))
        .build();
}

Subscriptions: For real-time updates, GraphQL subscriptions over WebSocket provide an elegant solution:

@SubscriptionMapping
public Publisher<BookCreatedEvent> bookCreated() {
    return bookPublisher.getPublisher();
}

Selecting the Right Framework

Each framework has its strengths, and the best choice depends on your specific requirements:

Spring for GraphQL is ideal if you're already using Spring Boot and want seamless integration with the Spring ecosystem.

Netflix DGS shines in microservices architectures and when you need powerful code generation tools.

GraphQL Java provides low-level control for custom implementations and is suitable when you need to integrate with specific technologies not supported by higher-level frameworks.

Apollo Federation is excellent for distributed systems with multiple teams working on different parts of the graph.

MicroProfile GraphQL fits naturally in Jakarta EE environments and enterprise applications.

Conclusion

GraphQL in Java offers a powerful approach to API development, with flexibility and type safety that traditional REST APIs struggle to match. The frameworks described above provide various ways to implement GraphQL services, from annotation-based simplicity to fine-grained control.

In my experience, the initial investment in learning GraphQL pays off rapidly through improved frontend-backend collaboration, reduced API complexity, and more efficient data retrieval patterns. The strong typing and introspection capabilities create a self-documenting API that evolves naturally with your application.

As you embark on your GraphQL journey with Java, consider starting with a framework that aligns with your existing technology stack. The learning curve might seem steep at first, but the resulting API will be more maintainable, flexible, and developer-friendly.

---

101 Books

101 Books is an AI-driven publishing company co-founded by author Aarav Joshi. By leveraging advanced AI technology, we keep our publishing costs incredibly low—some books are priced as low as $4—making quality knowledge accessible to everyone.

Check out our book Golang Clean Code available on Amazon.

Stay tuned for updates and exciting news. When shopping for books, search for Aarav Joshi to find more of our titles. Use the provided link to enjoy special discounts!

Our Creations

Be sure to check out our creations:

Investor Central | Investor Central Spanish | Investor Central German | Smart Living | Epochs & Echoes | Puzzling Mysteries | Hindutva | Elite Dev | JS Schools

---

We are on Medium

Tech Koala Insights | Epochs & Echoes World | Investor Central Medium | Puzzling Mysteries Medium | Science & Epochs Medium | Modern Hindutva