GraphQL is a query language for your APIs and a runtime for fulfilling those queries with existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more. GraphQL is designed to make APIs fast, flexible, and developer-friendly.
GraphQL SPQR
GraphQL SPQR (GraphQL Schema Publisher & Query Resolver, pronounced like speaker) is a simple-to-use library for rapid development of GraphQL APIs in Java. It works by dynamically generating a GraphQL schema from Java code.
In this tutorial, we are going to explain simple steps for how to integrate Graphql in your microservice.
- Include dependencies in pom.xml
<!-- GraphQL -->
<dependency>
<groupId>io.leangen.graphql</groupId>
<artifactId>spqr</artifactId>
<version>${graphql-spqr.version}</version>
</dependency>
<dependency>
<groupId>com.graphql-java-kickstart</groupId>
<artifactId>graphql-spring-boot-autoconfigure</artifactId>
<version>${graphql-spring-boot-autoconfigure.version}</version>
</dependency>- Spring Boot Java Configuration class:
@Configuration
public class GraphQLConfiguration {
@Bean
public GraphQLSchema schema(GraphQLRootQuery graphQLRootQuery,
GraphQLRootMutation graphQLRootMutation,
GraphQLRootSubscription graphQLRootSubscription,
GraphQLResolvers graphQLResolvers) {
GraphQLSchema schema = new GraphQLSchemaGenerator()
.withBasePackages("com.myproject.microservices")
.withOperationsFromSingletons(graphQLRootQuery, graphQLRootMutation, graphQLRootSubscription, graphQLResolvers)
.generate();
return schema;
}
@Bean
public GraphQLResolvers resolvers(MyOtherMicroserviceClient myOtherMicroserviceClient) {
return new GraphQLResolvers(myOtherMicroserviceClient);
}
@Bean
public GraphQLRootQuery query(MyOtherMicroserviceClient myOtherMicroserviceClient) {
return new GraphQLRootQuery(myOtherMicroserviceClient);
}
@Bean
public GraphQLRootMutation mutation(MyOtherMicroserviceClient myOtherMicroserviceClient) {
return new GraphQLRootMutation(myOtherMicroserviceClient);
}
// define your own scalar types (custom data type) if you need to.
@Bean
public GraphQLEnumProperty graphQLEnumProperty() {
return new GraphQLEnumProperty();
}
@Bean
public JsonScalar jsonScalar() {
return new JsonScalar();
}
/* Add your own custom error handler if you need to.
This is needed, if you want to propagate any custom information error messages propagated to the client. */
@Bean
public GraphQLErrorHandler errorHandler() {
....
}
}
- GraphQL class for query operations:
public class GraphQLRootQuery {
@GraphQLQuery(description = "Retrieve list of your attributes by search criteria")
public List<AttributeDTO> getMyAttributes(@GraphQLId @GraphQLArgument(name = "id", description = "Id of your attribute") String id,
@GraphQLArgument(name = " myQueryParam ", description = "…") String myQueryParam) {
return …;
}
}
- GraphQL class for mutation operations:
public class GraphQLRootMutation {
@GraphQLMutation(description = "Update attribute")
public AttributeDTO updateAttribute(@GraphQLId @GraphQLNonNull @GraphQLArgument(name = "id", description = "Id of your attribute") String id,
@GraphQLArgument(name = "payload", description = "Payload for update") UpdateRequest payload) {
return …
}
}
- GraphQL resolvers:
public class GraphQLResolvers {
@GraphQLQuery(description = "Retrieve additional information")
public List<AdditionalInfoDTO> getAdditionalInfo(@GraphQLContext AttributesDTO attributesDTO) {
return …
}
}
Note: All the Java classes (AdditionalInfoDTO, AttributesDTO, UpdateRequest) are just examples for data transfer objects and requests that needs to be replaced with your custom classes in order the code to compile and be executable.
- How to use GraphQL from client side?
Finally, we want to have a look, how GraphQL looks from the front end side. We are using a tool, called GraphiQL (https://www.electronjs.org/apps/graphiql) to test it.
- GraphQL Endpoint: URL of your service, defaults to /graphql
- Method: it is always POST
- HTTP Header: You can include authorization tokens with the request
- Left pane: the query, must be always in JSON format
- Right pane: response from the server, always JSON
- Note: You get what you request, only those attribute are returned which you request.
Simple examples for query and mutation:
In this tutorial, you learned how to create your GraphQL API in Java with Spring Boot. But you are not limited to Spring Boot for that. You can use the GraphQL SPQR in pretty much any Java environment.
