Switch from REST to GraphQL

[scottohara]

Our Rails backend is simply a JSON-based REST API (essentially what you now get in Rails 5+ when creating a new app with the --api flag).

Most controller actions do little more (if anything) than render json: <some model or collection>

We use ActiveModelSerializers to serialize models to JSON, which has it's own set of challenges.

Over the years, AMS became more of a first-class JSON:API implementation (we don't use JSON:API); and at this point is largely an abandoned project (has not see any progress in a number of years).

At the same time GraphQL has seen huge popularity, and many of it's benefits would fit our use case, e.g.

• Avoids overfetching - in the current REST API, if the client only needs a few fields from a resource, we either need to fetch the entire resource to the client, and pluck out the required fields; or we need to create a dedicated endpoint on the backend (new route + controller action) that returns only those fields.
• Avoids underfetching - i.e. N+1 queries from the client (though the only place where a potential N+1 scenario springs to mind is when finalising account reconciliation, where all transactions are updated from cleared -> reconciled).
• Statically analyzable queries - easily determine the exact data fields used by any client view.
• etc.

Given all of this, we should call a spade a spade, and consider ditching REST in favour of GraphQL.

Arguably this does mean abandoning some of the most fundamental parts of Rails, such as its router and controllers; but then again we're already not using large parts of the overall Rails framework (ActionView, ActionController, ERB, ActiveJob, ActionMailer, ActionCable, Sprockets, asset pipeline, Webpacker, etc.). The main benefit we get from having a Rails backend is ActiveRecord.

Investigate using something like graphql-ruby gem.

[scottohara]

Would also have the benefit of being able to get rid of the existing controller tests and replace with request tests (#115)

[scottohara]

In the 5 years since opening this issue, I've had an opportunity to work closely with GraphQL in another project, and I've reached the conclusion that it would not be warranted for this project for the following reasons:

• There is a single client (browser frontend)
• The specific operations needed by the frontend are already well supported by the current REST API
• The benefits of GraphQL with regard to over/under-fetching would be minimal (if any)
• There are significant complexities to GraphQL, such as observability, logging and monitoring that would need to be solved
• There is a strong desire to remain as close as possible to "vanilla Rails" to minimise complexity and make upgrading easy
• We may at some point move away from an API only backend (e.g. replace the JS SPA frontend with Hotwire?)

There is certainly still appetite to look at alternate JSON serialisation support to replace AMS, and improve inefficiencies such as category index, but GraphQL is not the right answer here.