Building a GraphQL Server with Java

For the purposes of this article, I’m going to assume you know what GraphQL is. If not, check out our first post in our GraphQL series, What is GraphQL.

JavaScript (NodeJS) seems to be the most popular implementation of GraphQL servers, but if you want to be a rebel and do it in Java then this is the right place for you! In this post, you’ll learn:

1. What’s going on in the open-source community around Java and GraphQL
2. A brief intro to some of the more popular Java libraries to help you decide which ones to utilize for building your GraphQL API.

Java/GraphQL Open-Source Landscape

GraphQL is a fairly new technology, having been released publicly by Facebook in 2015. As I mentioned previously, JavaScript appears to be the most popular implementation of GraphQL. Understandably so since, at that time, Facebook also released the JavaScript implementation for the GraphQL specification. I didn’t go into great depth to validate this conclusion with hard statistics, but I did take a quick look at the Github numbers on the various open-source projects that support GraphQL.

Here are some Github stats for the JavaScript implementation of GraphQL (as of Oct 9th, 2020)

and the corresponding stats for the Java implementation of GraphQL (as of Oct 9th, 2020)

All that to say, community support is not quite as strong for implementing a GraphQL server in Java as opposed to JavaScript. From what I’ve found, the documentation and tutorials for doing this in Java are a little rough around the edges. My hope is that the information in this post will save you some time getting up to speed on your options.

GraphQL supporting Java Libraries

graphql-java

This is the quasi-official Java implementation of the GraphQL specification. All the libraries I will talk about next build on top of this one. In my opinion, using it directly is very clunky and verbose, but you can certainly give it a try using their Getting Started Tutorial.

graphql-spqr

The acronym SPQR (pronounced like speaker) stands for “Schema Publisher & Query Resolver.” Basically, with this library, you can slap some annotations on the service and data classes, drop some boiler-plate code in the startup logic of the app, and you’ve got an exposed GraphQL API! No need to even write a GraphQL schema.

This is a very attractive option because you can get it going very quickly, especially if you’re adding GraphQL to an existing Java service. That being said, there are some trade-offs to this code-first approach. For one, this approach is the opposite of the schema-first (similar to “API first“) approach that GraphQL purports. As a result, you risk losing some benefits that come from a well-defined API contract. Some examples include having reduced ability for teams to work in parallel, a steeper learning curve for new developers, and decreased reuse across APIs. See this great article from Swagger for more details.

graphql-java-tools

Similar to graphql-spqr, graphql-java-tools also makes it easy to wire up your Java classes to the GraphQL schema, but this library takes more of a schema-first approach.

It helps you avoid a lot of the boiler-plate code and clunky data fetchers that are needed from graphql-java. Instead, you:

1. Define your GraphQL schema
2. Create some “Resolvers” to expose your data classes
3. Wire your Resolvers and schema file into the app’s startup code.

Of course, the downside is that it’s slightly more work than graphql-spqr, since you have to actually build the GraphQL schema, but I believe there are some benefits to thinking through your schema/contract first before writing/rewriting code.

graphql-spring-boot

Here you’ll find a Spring Boot starter that provides graphql-java-tools in a Springified (because that’s a word) manner!

This even further reduces the boilerplate configuration needed since this reduces step 3 in the graphql-java-tools section down to creating beans out of your Resolvers. The Spring Boot starter will automatically scan the classpath to find your GraphQL schema file, making it a fairly minimal amount of work to get your GraphQL schema connected to the underlying Java classes.

Conclusion

You may have picked up on this already, but, of these libraries, my preference is graphql-spring-boot. It supports a schema-first approach, which is more in line with GraphQL’s strategy and advantages. Also, it does a lot of the boilerplate configuration for you, making it simple to expose your Java service as a GraphQL API.

I do want to clarify that I have not gone over every open-source Java library that supports building a GraphQL API; there are way too many to fit into a single article. I tried to focus on the most core/popular frameworks that I found in doing my research and hands-on experimenting.

Speaking of experimenting, I have published the Spring Boot GraphQL API that I made using graphql-spring-boot on Github, if you’re interested. Perhaps if there is any interest and if I find the time, I will post another article explaining that app in a tutorial format.

Now that you’ve read a bit more about GraphQL, it might be worth checking out our previous post, Is GraphQL Right for My Project?