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.
Create a Spring Boot app using the Spring Initializr. Select:
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".
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.
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:
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.
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">
Edit the query on the left-hand pane:
Click "(Run query)" or "Send Request".
You should see a response like this.
We have built a GraphQL server and run our first query!