Following the Spring GraphQL project announcement and the availability of a 1.0 milestone, this blog post aims to provide more details.
If you don’t know much about GraphQL, there are plenty of good resources. You can start at graphql.org/learn.
As Andy Marek wrote in the opening blog, Spring GraphQL was conceived as the successor of the GraphQL Java Spring project from the GraphQL Java team. This is why the initial focus of our collaboration was to match that functionality as well as integrate GraphQL Java and Spring in the best possible way.
To that end we created the following foundational support:
- HTTP handlers – available for both Spring MVC and WebFlux, built on WebMvc and WebFlux functional endpoint APIs.
- WebSocket handlers – following the protocol from graphql-ws with support for GraphQL subscription streams.
- Web Interception – ability to intercept every GraphQL request, inspect HTTP headers, and modify the GraphQL
- Boot starter – put it all together into a runnable application.
Beyond that we started looking at key aspects such as security, testing, and metrics.
The URL for a GraphQL endpoint is easy to secure as usual. For more fine-grained security, applications can use Spring Security annotations on data retrieval methods. This requires Spring Security context to propagate to data retrieval methods, and while GraphQL Java is neutral to threads, components in the execution can themselves be asynchronous and cause a switch of threads.
This lead us to add support for context propagation from the Web framework level, through the GraphQL engine, and to data fetching components. This includes both
ThreadLocal context and Reactor
Context for Spring MVC and WebFlux applications respectively. After those features are in place, Spring Security works without the need for any further specialized integration.
Spring GraphQL enables applications to create multiple, independent
GraphQlExceptionResolver components to resolve exceptions to GraphQL errors for inclusion in the GraphQL response. It also provides an
ErrorType type to use to classify errors with common categories such as
INTERNAL_ERROR by default.
You can test GraphQL requests using WebTestClient, just send and receive JSON. However, GraphQL specific details make this approach more cumbersome than it should be.
This is why Spring GraphQL includes
WebGraphQlTester that defines a workflow for testing GraphQL requests. It provides the following benefits:
- Verify GraphQL responses are 200 (OK).
- Verify no unexpected errors under the “errors” key in the response.
- Decode under the “data” key in the response.
- Use JsonPath to decode different parts of the response.
- Test subscriptions.
All samples use the
When the starter
spring-boot-starter-actuator is present, metrics for GraphQL requests are collected, including request and
DataFetcherexecution timers, and an error counter.
Querydsl provides a flexible and typesafe approach to express query predicates. Spring GraphQL builds on the Spring Data Querydsl extension to make it easy to create a Querydsl backed
DataFetcher. It prepares a Querydsl
Predicate from GraphQL request parameters, and uses it to fetch data and that works for JPA, MongoDB, and LDAP.
The webmvc-http sample uses Querydsl.
GraphQL provides a schema language that helps clients to create valid requests, enables the GraphiQL UI editor, promotes a common vocabulary across teams, and so on. It also brings up the age old schema vs object-first development dilemma.
Our take is that schema-first development should be preferred. It facilitates a conversation among people of technical and non-technical background, it helps with tooling, it makes it easier to track changes, and so on. There is also no one-for-one mapping between GraphQL schema and Java types.
That said there is room for code generation too, to get started, for clients to create queries, and so on. Frameworks like Netflix DGS have excellent support for this that can be used with Spring GraphQL.
We intend to have a 2nd milestone before SpringOne, September 2-3. We have a number of issues for M2 in the queue already from early feedback, including support for a GraphQL client, BatchLoader registrations, file uploads, and more.
The milestone phase will continue until after Spring Boot 2.6 in November, at which point the Boot starter is scheduled to move into the Spring Boot repository, for inclusion in Boot 2.7.
We aim to have stable APIs and enter an RC phase late this year. To get there, we need your feedback. Please, give it a try, and create an issue, or comment under existing issues in our issue tracker.
For more details on Spring GraphQL features, please check the reference documentation.
The GraphQL Java and Spring teams will present jointly at this year’s SpringOne conference, which is once again free and online for a second straight year. Please, register to attend our talk and to interact with speakers and attendees.