Strategy for migrating REST API to GraphQL - introduction ( Ruby on Rails )

Sommaire

Motivations
Action plan
Links

This article aims to give feedback on the migration of our REST API to GraphQL, as well as to present the action plan that was put in place.

Although we use Ruby with Ruby On Rails, this action plan is valid for other frameworks!

Motivations

Why move from REST to GraphQL?

Several reasons come to mind, the first of which is flexibility.

First, a bit of context: at the time of the migration we were a small team of developers: 2 frontend developers, 1 backend developer, 1 full-stack lead. We were responsible for several front-end applications that consumed an API ( our backend ).

REST is perfectly suited for this type of project; however, for our small team, our frontend developers would sometimes be blocked by a missing API endpoint, still under development, to implement/finish a feature.

Another reason cited is GraphQL's use case itself: it offers flexibility that allows frontend developers to specify the responses and data formats they want.

A certain freedom is therefore offered to frontend developers during their development, they can express queries that are specifically tailored to their interfaces.

Is REST outdated?

No! I think REST remains a good approach; some backend complexities introduced by GraphQL (notably server-side caching) have simple solutions with a REST approach. That said, GraphQL's growing popularity suggests that its adoption is real, and will eventually coexist with REST APIs.

I'm interested, tell me more

I propose the action plan we put in place to provide continuity of service for the applications and clients that consume the REST version of our service, while creating a GraphQL version of our API.

Action plan

Preparatory work

List the controllers & actions that will be present in the GraphQL version of the API.
Extract controller actions into objects (inspired by the "command" design pattern).
Update the test coverage.

Routing configuration

Implement the routing strategy: filtering and routing by header "accept".

Installation and configuration of GraphQL

Install GraphQL.
Create GraphQL models specific to the ActiveRecord models.
Create the various queries & mutations.

Conclusion & feedback

First of all, the preparatory phase allowed us to do a good cleanup of our code base: we were able to identify unused code, refactor and optimize code that deserved it, and improve our overall test coverage.

Then, implementing a routing strategy based on the "Accept" header allowed us to have both API versions coexist, providing continuity of service for the different consumers of our API.

Finally, GraphQL is relatively well integrated into the Ruby on Rails ecosystem. Numerous articles and tutorials are available online. Some important concepts such as schema obfuscation, creating custom types, authorizations, etc. are very well explained.

Regarding day-to-day use on the frontend side, once the time for setup and migration ( axios → appolo ) had passed, using GraphQL allowed our frontend developers to gain autonomy and productivity.

In my opinion this decision was the right one for our team; it allowed us to add value to our API in terms of functionality but also robustness thanks to the various refactors and the improvement of our test coverage.

What's next?

I will write a series of articles that will go into more detail on some key steps presented in the action plan.

In the meantime, here are some useful links related to the topic of the post.