The title of this article could just as easily be “Why I never want to work on another REST API ever again”, or perhaps more mildly “Why GraphQL and Why Not REST?”
I am writing this on the heels of a second read-through of “REST vs GraphQL: A Critical Review” and felt that Z’s article is minimizing the benefits of GraphQL in a way that makes REST look like it can still be a plausible solution to enterprise business needs.
Expressed with more verbosity, REST is not a pattern you should use to build new APIs unless that API is both built and maintained by the same developer forever and you never expect to grow/change the team or the code base. And even then...
Who am I?
I am what some might call a senior enterprise web application developer. Having worked in agencies for the last 15 years of my life, I know what it takes to drive a project from start to finish. I was contracting my web development expertise to friends and family at 12 years old. I’ve scoped projects, had to work on projects scoped by others, and I have seen many web applications rise and fall for the same reasons.
Why REST Causes Web Application Projects to Fail
Businesses are all about solving their problems quickly, with as little money as possible, and in a way that provides lasting relief. Thus, web application development projects are both time-constrained and resource-constrained in most cases.
Good developers which deliver quality solutions quickly are both hard to find and expensive to retain. To ship a quality web app before the money runs out, you need (among other things) an API that does not require an army of talented engineers to build, maintain, and consume.
A REST API requires developers to go down one of a couple paths: expose and consume resources across multiple endpoints (‘optionally’ preserving that information client-side while navigating an SPA), or consume different endpoints with giant JSON responses for each page.
The first path results in lots of network overhead and lots of skilled developer time exposing, documenting, and optimally consuming the different resource endpoints; some of the best developers I know who have since gone on to work for Google, Amazon, etc. still get this wrong. The second path results in lots of network overhead and more developer time spent maintaining different endpoints for each page which often return vastly similar data structures.
Both paths result in versioning requirements if you want to re-architect your API and support existing clients at the same time. None of this even talks about the different client-side tools for consuming REST APIs / managing state, and the multiple headaches associated with them (Redux
sagas/thunks/actions/reducers boilerplate, Angular 1 2 4 5 6 Dart, jQuery?, etc…)
At the end of the day, the documentation is still out of sync, the project is still behind schedule, and the app still needs 5 more endpoints. Atleast.
How GraphQL APIs Deliver
For this, I would like to share a story with you -- a brief story based on real-life, and to which you can likely relate.
Having just inherited a legacy codebase (read: lack of tests, lack of documentation, etc), I was tasked on “getting the thing to work.” Basically, a core component of the web application (admittedly unrelated to REST) had unfortunately under-delivered and failed to meet the business needs of the company. So, here I was, the sole-replacement for a team of 10+. I became project manager, product owner, lead developer, and designer.
In spite of this, over the next few months I did manage to get the thing to work. However, a new challenge lurked just over the horizon. With great success comes new responsibility, and now we were looking at a target market with very high-stakes security concerns. Given the legacy nature of the existing codebase, the three different files for password reset functionality (all of which were insecure and only one of which was in use) and a myriad of other side-effects of REST-based development, I knew we were in for a full rewrite to meet this goal. It ~cannot~ can, but it's much harder and more expens