GraphQL had been on my ‘one to watch’ list for some time. Upon casual glances it looked both expensive to implement and lacked any burning issue it could solve (at least for me). So there it sat. Then GitHub announced they were adopting GraphQL for their next generation public api, and around the same time, our micro-service based product started having growing pains. Those growing pains came from the disparate API jungle our consumers needed to navigate. Was a GraphQL server the answer?
Our micro-services had grown in number. They (mostly) produced server-side designed API endpoints that mapped out each micro-service domain object graph. The API endpoints ranged from very specific consumer needs to the ’all you can eat’ API query that returned everything. There were several notable patterns to appear:
Consumers had to call multiple micro-service APIs to collate all the data needed to render a page, or for their own service logic
Micro-services that contained linking identifiers started to request these downstream domains to enrich their own query API
Consumers would find and call an existing coarse-grained expensive API endpoint just to get a couple of odd fields
If you take a look at the http://graphql.org website you’ll see a very polished product. It looked to be a potential solution to our API growing pains, and, what I hadn’t really appreciated in my earlier glancing is that the complexity of creating the server side processing engine is already provided in several languages. So not only is GraphQL a ‘query language syntax’, but also the ‘query language processor’. That just leaves wiring up your data.
Not only is GraphQL a ‘query language syntax’, but also the ‘query language processor’. That just leaves wiring up your data domain.
Further searching revealed very few samples for Java based GraphQL server. So here I’ve pulled together a multi-module Java project to test out a Java based GraphQL server backed by several REST micro-services. Hopefully the code and README in GitHub overview will give you enough depth to explore it yourself.
Maturity, Documentation and Community
GraphQL has been around a long time and being used by FaceBook and GitHub is a massive endorsement of maturity, as well as confidence for production readiness.
GraphQL sweet spot for me would be for aggregation of many micro-services and/or data-sources. Creating such a GraphQL service on the borders of your platform comes with benefits on both sides
It solves a very real problem, especially for larger platforms. There’s excellent client-side documentation and while the server-side documentation is not so polished the graph-java implementation works as expected out the box. I was pleasantly surprised at how quickly I became productive.
At the time of writing the graphql-java server implementation project seemed to be the most mature, with supporting projects like graphql-java-tools (defining a schema with a mix of schema text definition and code mixin), graphql-java-annotations (defining a schema with objects and annotations) and graphql-spring-boot (auto wiring into SpringBoot), either not quite ready for prime time or somewhat limited.
Right Tool for the Right Job
GraphQL sweet spot for me would be for aggregation of many micro-services and/or data-sources. Creating such a GraphQL service on the borders of your platform comes with benefits on both sides:
Consumers can get a well defined schema with documentation
Consumers can group and fine tune their queries to give them only what they need in a single call
Your platform has a pinch point to apply caching, mapping adjustments, aggregation, and data enrichment
Your platform has a much clearer understanding of what data the consumers really are using, and not using, which will aid data model evolution
…most of the above benefits outweigh the costs and challenges:
Another repetitive object mapping layer to maintain (add GraphQL schema to your DTO and JPA schemas)
You must completely know schema of downstream you wish to expose (e.g. all possible enum values)
You need to manage data fetching efficiently, implement your own performance, caching, and pagination solutions
You need to hook into your security model (in most cases you can get away with simply passing through the authentication data)
The effort to stand up a GraphQL server is a lot simpler than you might think at first glance. In reality, you are just plugging in a processor framework and thereafter defining your data schema mappings and data fetching adaptors. It lives quite comfortably within your existing security and data source technologies.
GraphQL could replace REST in all your micro-services. Whether this is a good idea will be very specific to your situation. REST is more universal and there are more tools for REST based API management and monitoring, not to mention a lot more familiarity across the developer community. That said, I could see some micro-services with larger datasets benefiting from exposing a GraphQL endpoint alongside a traditional REST API. For example, this would be a better way to implement a powerful ‘search’ like REST API endpoint than trying to cook your own using REST query parameters.
Finally, the GraphiQL tooling is a killer feature. Even if not something for production access it can be a massive aid to learning, schema design process, and manual testing.
Overall a very impressive technology that will definitely be moving from evaluation spike to production spike.