GraphQL on Rails, part 1/2

A exploration of using GraphQL to query a Rails 5 API. This is part 1 of a 2 part series.

At Tenavox, we use a standard REST API to power each of apps: our Tenant-customer front end, our in-house administrative back end, an app dedicated to Brokerage Reps to manage their buildings, and all of our front-facing free Tenant tools, such as our LeaseGrader. All in all, it’s worked out well by using what I’d describe as “standard” Rails 5 API patterns, inspired from jsonapi.org

Along the way, though, we’ve noticed a few speed bumps. In particular, the advantages gained by a full standardization of REST calls implies a API endpoint for each of the resources available to be served up. While this was great at first — much like Rails itself the enforced conventionalization of the API had a comforting feel — it seems to appeal most to the strictly-trained CS folks on our back end team and less so to our front end developers. A sort of “do it this way this time, and next time, and every time, … ” rigidity effect.

Added to that, when the front end folks (or any new dev joining the team) wanted to a specific set of data about a resource including data that might be associated with the resource (say, ‘buildings and some rate quotes for space in a given region’) as well as info that clearly was not related to it in the domain space but frequently useful to the end Tenant customer contextually (say, ‘distance to the nearest coffee house’), the solution was a choice of

1. make multiple calls to the API to get the info from each resource
2. make a request from the backend team for a new resource that umbrellas all this data
3. expand the scope of data returned from an existing resource endpoint to include everything that might be useful, regardless of the context of a given request

You can see the problem here, a problem common to REST generally. In case (1), more calls does not scale well, and loads the system needlessly. Case (2) keeps the calls under control, but overloads the size of the API to be learned . And case (3) almost gives up REST as it feels like violating its philosophical basis.

I might add a 4th problem, which concerned me far more: in all three cases, the frontend devs had to make a request to the backend devs that often took at least a 2-week sprint cycle to make it from staging to production.  It’s not that there was anything wrong with REST, but I did feel reminded of what Emerson said about a “foolish consistency”; it did feel like it was causing a drag on front end development solely for the sake of a consistency only the backend devs could maintain.

I happened across GraphQL at that time, having heard some buzz here and there, and encouraged by Github’s adoption of GraphQL. The philosophy is quite different: describe to the API what you want, and let it come back with its interpretation of how to serve up a response to your query. Maybe it was worth trying out. Sort of a Just-in-Time querying of an API.

Part 2 of this post will walk through a simple approach to using GraphQL to serve up data from a Rails 5 app. My hope is that you too will try it for yourself and maybe you’ll use it on an upcoming project.