GraphQL Java Server Example

In this tutorial, you will create a GraphQL server in Java using Spring for GraphQL.

This How-To is completely copied from the Getting started with Spring for GrapQL tutorial. We use Maven instead of Gradle and a slightly different code. For you convenience the explanations from the original tutorial are copied here or links are provided to precise sections.

Read the short GraphQL Java Overview to learn a bit about the 2 main components of our server: an engine in charge of executing data queries and another that deals with the JSON and HTTP aspects.

We will develop a server that provides information about books. Read the very short introduction to GraphQL and the example presentation.

Project Creation

Create a Spring Boot app using the Spring Initializr. Select:

screenshot of Spring Initializr

Click "GENERATE" and download the bookinfo.zip file.

Uncompress the file: unzip ~/Download/bookinfo.zip

Start Eclipse IDE, File menu, "Open Projects from File System...", "Directory...", select Home Downloads/bookinfo/ and click "Open" and "Finish".

Data

Create a directory src/main/resources/graphql.

Add a new file schema.graphqls to src/main/resources/graphql with the following content:

This schema defines two top level fields (in the type Query): bookById which returns the details of a specific book, and authorByLastName which returns information of a given author.

It also defines the type Book which has the fields: id, title, pageCount and author. author is of type Author, which is defined after Book.

The Domain Specific Language (shown above) used to describe a schema is called the Schema Definition Language or SDL. More details about it can be found here.

Data Source

Add the following com.graphqljava.tutorial.bookinfo.Book java class:

Add the following com.graphqljava.tutorial.bookinfo.Author java class:

To simplify the tutorial, book and author data will come from static lists inside the following Library class. It is very important to understand that GraphQL doesn't dictate in any way where the data comes from. This is the power of GraphQL: it can come from a static in-memory list, from a database or an external service.

Add the following com.graphqljava.tutorial.bookinfo.Library java class:

Adding code to fetch data

Spring for GraphQL provides an annotation-based programming model to declare handler methods to fetch the data for specific GraphQL fields.

Add the following com.graphqljava.tutorial.bookinfo.LibraryController java class:

The @QueryMapping annotation binds this method to a query, a field under the Query type. The query field is then determined from the method name, bookById. It could also be declared on the annotation. Spring for GraphQL uses RuntimeWiring.Builder to register the handler method as a graphql.schema.DataFetcher for the query field bookById.

In GraphQL Java, DataFetchingEnvironment provides access to a map of field-specific argument values. Use the @Argument annotation to have an argument bound to a target object and injected into the handler method. By default, the method parameter name is used to look up the argument. The argument name can be specified in the annotation.

The @SchemaMapping annotation maps a handler method to a field in the GraphQL schema and declares it to be the DataFetcher for that field. The field name defaults to the method name, and the type name defaults to the simple class name of the source/parent object injected into the method. In this example, the field defaults to author and the type defaults to Book. The type and field can be specified in the annotation.

For more, see the documentation for the Spring for GraphQL annotated controller feature.

That's all the code we need! Let';s run our first query.

Running our first query

Start the Spring application: run the BookinfoApplication class.

Use the Altair GraphQL client pluggin in Firefox and enter the endpoint http://localhost:8080/graphql.

Click "Docs".

On Altair right-hand pane, click "Query", then move your mouse to the right of "bookById" and click "ADD QUERY">

screenshot of Altair showing the list of possible queries and the ADD QUERY button

Edit the query on the left-hand pane:

Click "(Run query)" or "Send Request".

You should see a response like this. screenshot of Altair showing the query and response

We have built a GraphQL server and run our first query!

code on Git