GraphQL offers a new style of API design intended to provide API consumers with unified access to back-end data and services. In spite of this seemingly universal aim, GraphQL has created a schism in the API community between those who believe it is superior to state of the industry RESTful API design and those who believe it is naively re-introducing solved API design problems. This blog examines GraphQL, the API community’s dichotomous emotional responses, and concludes that the truth about GraphQL lies somewhere in between.
These are interesting times in the world of APIs. After a decade of RESTful* APIs dominating the landscape, a new crop of API protocols and design approaches have emerged. I wrote a piece for InfoQ earlier this year, “Overcoming RESTlessness,” that explores GraphQL, gRPC, event distribution, as well as the current state of REST. I’ll be giving a talk on that topic next week at the API Specifications Conference in my hometown of Vancouver. I won’t restate that piece here, but I want to delve deeper into a related topic that has fascinated me for the last couple of years: why does everyone get so emotional about GraphQL?
The rise of GraphQL
The Facebook Engineering blog post that announced the open-sourcing of GraphQL was the spark that lit the emotional firestorm. In it, Lee Byron expresses his frustration with the need to make multiple back end calls caused by Facebook’s REST conventions. He clearly touched a nerve. The first wave of GraphQL blog posts were all about its superiority over REST and often bemoaned the multiple call issue along with REST’s perceived inflexibility. The titles of these posts — “REST for Web Apps Is So Passe,” “GraphQL is the better REST,” “Why GraphQL is the future” — expressed the seeming euphoria their authors felt in using this new protocol that removed the source of their suppressed irritation. A new set of vendors who sensed the opportunity of providing tooling for the new approach also stoked the fire.
All this heat got the attention of another group of people who had pent-up emotions of their own. Ever since REST became the predominant architectural style for web APIs, there had been debates within the API community about what constituted REST. The most popular implementation approach mapped HTTP methods (GET, PUT, POST, DELETE) to URL-defined resources, allowing for simplistic data querying and manipulation. However, this “pragmatic REST” style failed to implement the full set of constraints described by Roy Fielding in his Ph.D. dissertation that defined REST in the first place, most notably the hypermedia constraint. The community of API experts who knew REST best were quick to point out the issues they could see with the “pragmatic” approach: specifically, it promoted tight coupling between consumers and providers, limited the scope of tasks that could be completed by a single API call, and impeded the overall evolvability of the API. In spite of these warnings, API implementers kept rolling out pragmatic REST APIs while consumers dealt with the resulting issues.
The API community gets restive
When GraphQL came along with its promise to liberate API consumers through a new protocol, REST API experts were triggered in two ways. First, they felt you didn’t need a new protocol to fix the issues with pragmatic REST APIs, you just needed proper REST. Secondly, they felt the new protocol itself had issues of its own.** GraphQL’s schema-based model was seen to compound the tight coupling between consumers and providers. Unconstrained queries could lead to unpredictable back-end workloads. Security was a question mark. And the promise to “get data from any source through a single interface” smelled a lot like the ESB approach that had fallen from the industry’s favour for other reasons. Kin Lane’s first blog post on GraphQL summed up the API experts’ opinions well. So now you had a group of enthusiastic developers advocating for GraphQL as an alternative to REST, and a group of REST experts pointing out that the GraphQL advocates weren’t hating on REST at all, and might be headed for some unseen pitfalls.
Since GraphQL was launched, many companies have chosen to use it for their APIs. There has been some great work by API experts like Phil Sturgeon, Zdenek Nemec, and James Higginbotham to help parse the post-GraphQL API landscape. However, the two camps continue to butt heads, with plenty of “GraphQL is magical” and “REST is best” posts still being published. I think the false dichotomy — it was never about GraphQL vs. REST — persists because the emotion persists. I also think the best way to bring the emotions down and the reason up is to have some shared understanding between the GraphQL advocates and the REST experts. Here is my advice to both groups…
To the REST experts:
- Instead of rushing to judgment, do some learning. GraphQL’s name is misleading. More API scenarios are supportable than you think.
- Understand where GraphQL came from. Its popularity is being driven by front-end developers moving to frameworks that include native GraphQL support, and away from frameworks (e.g. Ruby on Rails) that promote pragmatic REST. Within this context, the popularity is understandable.
- Think about what is leading to GraphQL adoption beyond the protocol itself. Top-notch tooling makes GraphQL very appealing to client developers. High-profile adopters like Facebook, Github, and Netflix provide confidence.
- Remember that you were once the rebels throwing shade at SOAP, the one time API protocol incumbent.
To the GraphQL advocates:
- Learn the broader API space. Learn REST beyond the CRUD style you’ve had to deal with. Especially learn the concerns that experienced API architects have about GraphQL.
- Make sure you understand which benefits come from the GraphQL protocol, which come from the topology (a gateway that aggregates data from multiple sources), and which come from the tooling. As Phil Calcado points out, you can get some of these benefits without using GraphQL at all.
- Respect REST’s ubiquity. The fact that REST may have been used in places it wasn’t intended for is a testament to its usability. On top of that, 15+ years of widespread usage has cultivated a massive ecosystem of tools, language support, specification formats, security approaches (e.g. OAuth), reference implementations, and other artifacts. Even if these aren’t reasons to select REST, they can be used to shortcut some of the efforts to make the GraphQL ecosystem as robust.
To both groups:
- Don’t get tied to one protocol. The most well-designed APIs have separation between their interface semantics and syntax. Supporting multiple protocols for a single API is ideal from the consumer’s perspective. Being able to quickly add support for new protocols is equally important.
With the continued growth of APIs in the industry, it’s a reality that not everyone is going to come to consensus on protocols, styles, or paradigms. But we can and should learn from each other. Rather than tearing down the old foundation — a tragic tendency of software engineering trends — let’s see if we can co-evolve. I will explore that thinking in my ASC talk next week. The event also features MuleSoft experts Jonathan Stoikovitch and Antonio Garotte, as well as some of the brightest experts in the API industry like Taylor Barnett, Mehdi Medjaoui, and the aforementioned Kin Lane and Phil Sturgeon. Hope to see you there!
* I’m including both the original definition of REST from Roy Fielding and the common CRUD-like interpretation.
**Third would be the hubris of the founders, who had a documentary made about the creation of GraphQL, but I digress…
