Practical GraphQL
Get some quick gains with GraphQL
I have been reading about GraphQL for some time and the question that always arises, once I’ve gone past the hype of using a new technology, how can this practically benefit me?
Disclaimer: This is not an introduction to GraphQL. This is an exploration of how GraphQL can be introduced into an existing architecture and what the benefits would be. For an introduction to GraphQL see here.
To get a sense of where GraphQL can fit in, let’s quickly review a traditional microservice architecture (if you are still sitting on a monolith then GraphQL has a way to help, too, as a way of gradually transitioning toward a microservice architecture).
The channel specific services are your UI layer combined with what is often referred to as BFF — Back-End for Front-End. These Channel APIs have little business logic and are focused on providing data in a way that makes a lot of sense to the UI so that the user experience can be optimized.
But Domain Specific APIs on the other hand deliver data that is representative of the domain. They aim for completeness of representation.
For example, lets look at Google’s Geocoding API:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Google Building 41",
"short_name" : "Google Building 41",
"types" : [ "premise" ]
},
{
"long_name" : "1600",
"short_name" : "1600",
"types" : [ "street_number" ]
},
{
"long_name" : "Amphitheatre Parkway",
"short_name" : "Amphitheatre Pkwy",
"types" : [ "route" ]
},
{
"long_name" : "Mountain View",
"short_name" : "Mountain View",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Clara County",
"short_name" : "Santa Clara County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "California",
"short_name" : "CA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "94043",
"short_name" : "94043",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 37.4228775,
"lng" : -122.085133
},
"southwest" : {
"lat" : 37.4221145,
"lng" : -122.0860002
}
},
"location" : {
"lat" : 37.4224082,
"lng" : -122.0856086
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 37.4238449802915,
"lng" : -122.0842176197085
},
"southwest" : {
"lat" : 37.4211470197085,
"lng" : -122.0869155802915
}
}
},
"place_id" : "ChIJxQvW8wK6j4AR3ukttGy3w2s",
"types" : [ "premise" ]
}
],
"status" : "OK"
}This is a big result and your front end generally woudn’t need all of this, and especially if we are dealing with more than one such result, iterating, manipulating etc. all of these slows down the user experience and bloats your codebase. Chances are, you just want the location coordinates or something similar. The BFF would allow us to wrap this domain specific api call with something more manageable like:
{
"location" : {
"lat" : 37.4211470197085,
"lng" : -122.0869155802915
}
}If the Google Geocoding API represents something from your company’s Domain Specific API layer, your BFF would have a couple of end points to expose this to the UI layer like:
/coordinates?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA
/postal-code?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA
This, from a traditional MVC perspective, means we have a single controller for each end point and some logic to expose just the data that is required.
That’s fine. But now imagine a couple of channels, each owned by a different team. At least a couple of BFF controllers would be returning the same result. And if you needed one additional piece of data (or one less) you’d have to set up a new endpoint.
For smaller teams this can quickly turn into quicksand. Even for larger teams this can slow them down.
Let’s bring in GraphQL
Rest means Representational State Transfer — which implies each url represents an object. GraphQL on the other hand, suggests that a single endpoint can give you different objects, but all objects at that url path will obey the same schema.
Going back to the Google Geocoding example, our schema would be represented by the entire json object that Google returns — with maybe some transformation to optimize our use case.
A GraphQL query can then simply ask for what it wants out of that schema like:
location?query={address(street:1600+Mountain+View) {location}}
This would return just our coordinates.
location?query={address(street:1600+Mountain+View) {code}}
This would return just the postal code.
location?query={address(street:1600+Mountain+View) {location, code}}
This would return us both.
This is clearly very flexible and powerful. If a new UI feature requires new data points to be exposed, we don’t need to write new back end code. We just change the query.
From an operational perspective, we reduced 4 repos, with their respective deployment pipelines and hosting requirements, to just one repo with one deployment pipeline. Less to maintain, less to monitor.
GraphQL works using schemas that can be accurate representations of domain objects or even compositions of domain objects. As such, the only time a code change in the GraphQL layer is required, is when a new schema is added — which means you are adding a new domain service which probably is not a daily occurrence.
Conclusion
For small teams, GraphQL provides a huge simplification of their API layer which connects the back end data infrastructure to the front end presentation layers. It will reduce complexity and increase maintainability.
Now, the hard part — convincing your team to use it.
