Earlier this year I took on the task to develop an API Strategy for our application. We have API routes now. They just don't all follow the same rules.

Here's the criteria our web and mobile developers wanted for our API:

  • Consistency. How we make requests. Data in the response.
  • Strongly typed. Mobile and React developers like strongly typed data.
  • Documentation tied to the code. Trying to synchronize code changes with documentation in comments or a separate document failed for us in the past. The only way they can be truly in sync is if our code provides the docs.

There were others, but those were our primary concerns.

GraphQL wasn't initially on the list

I started our overall API Strategy without GraphQL being a consideration. I felt it would be too big of a change. It was too new.

However, it kept coming up in my conversations with developers. Are you considering GraphQL? was a recurring question.

Therefore, I included it. And not knowing much about GraphQL, did a lot of reading.

We have a Rails application, so I also created some examples converting a few of our existing API routes to see what development would be like using the GraphQL Ruby gem. Also to allow mobile developers to check it out.

GraphQL hits the spot

GraphQL hit on all of our criteria, and mobile development particularly liked how they could ask only for the data they want within a query. A concern as sometimes our users can be in areas without great connectivity.

I was skeptical initially, but GraphQL won me over. It really does feel like a next-generation API.


Reading posts from other folks, there were a couple of recurring issues brought up with GraphQL.


Being a query language, GraphQL doesn't really concern itself with caching at all. Queries are submitted via a POST request to the server, and since a query does not have a specific URL that's cacheable, people tend to wave their arms around and complain a lot about it.

It's not something I'm overly worried about. The Apollo GraphQL client library, available for the web, iOS, and Android, has functionality for client-side caching. And with a Rails server, I have faith in our developers doing what we need in regards to caching on the server if we do need to address it there.

N+1 queries

Another common item folks point out are N+1 query issues.

GraphQL can be implemented in any various language, so it may be more of a problem with some language implementations than others. We use Rails. I'm optimistic that great tools like GraphQL:Batch can help us overcome these issues when we face it.

The journey forward

We're just getting started and likely have some failures in our future. Regardless, I'm optimistic on where we're headed. In the coming months, I hope to share our experience as we ramp up our GraphQL development.

Also posted at the Tech at Power blog.

Top photo credit: unsplash-logoFabrice Villard