GraphQL is a query language built by Facebook. It is an alternative to building REST APIs. In the last few years it has become popular and there are many big organisations like Facebook, Github, NewYork Times, Shopify, Walmart Labs, and many others that are using it to build their web applications.
GraphQL is a query language and a runtime system. Clients form requests (called queries and mutations) by using the GraphQL query language, and the GraphQL server executes the request and returns the data in a response. Unlike REST APIs, which expose a different endpoint for each resource object, a GraphQL API makes all data available at a single endpoint. A client specifies exactly the data that it wants, and the server responds with only that data.
For last few months I am thinking to spend time learning about GraphQL but before I get deeper into GraphQL I wanted to understand why many organisations are adopting it. So, I spent a day reading GraphQL case studies mentioned on the GraphQL website.
Below are the main reasons why an organisation should adopt GraphQL.
Reason 1: Flexibility
When organisations talk about flexibility they mean many things.
- Clients have the flexibility to ask what they want using the GraphQL query language
- Clients have the flexibility to ask associated data in a single HTTP request. This means you can avoid making multiple HTTP REST API calls to fetch associated data.
- Clients have the flexibility to coalesce multiple fetches into a single request
Github in their blog said:
The ability to define precisely the data you want—and only the data you want—is a powerful advantage over the REST API v3 endpoints. GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify.
Walmart Labs engineers in their blog on GraphQL adoption write following:
Each of these teams has vastly different requirements on what subset of transaction data it needs to access. Making our data easily consumable, especially since we’re a small group of engineers, is a core challenge that a traditional REST API structure wasn’t solving for us.
Over time, we found ourselves in the unenviable position of maintaining, extending, and documenting a collection of APIs, each initially built for a specific use case. Each of these API used a different HTTP stack, was configured differently, and had its own ad hoc conventions for URL schemes, query parameters, and so forth, as inspired by the practices at the time they were built.
Reason 2: Mobile friendly
Because client has the flexibility to ask what they need GraphQL enables clients where smaller payload sizes are essential.
For example, a mobile app could simplify its requests by only asking for the data it needs. This enables new possibilities and workflows that are freed from the limitations of downloading and parsing massive JSON blobs.
The rise in importance of mobile application performance and organizational agility has provided booster rockets for GraphQL’s ascent to the top of modern enterprise architectures.
Reason 3: Strong typing
Shopify mentions in their documentation
REST | REST APIs are usually weakly-typed and lack machine-readable metadata
While there exists some solutions to the problem of not knowing which data is being used (like JSON Schema), the reality is that most REST APIs do not provide this sort of metadata. The result is that apps rely on documentation, which can become out of date or might be incomplete.
GRAPHQL | Everything is typed and part of a schema
Everything that’s available through a GraphQL API is included in its schema. You can use the schema to build queries that return only the data that you need. This solves the problem of over-fetching data. It also means that we know which fields each app is using, making it easier for us to evolve our APIs over time.
Reason 4: Incremental adoption
Coursera mentions how they were able to adopt GraphQL in incremental manner.
After some investigation, we found a great approach to help us get to GraphQL — we decided to add a GraphQL proxy layer on top of our REST APIs. This approach is actually pretty common and has been very well documented, so I won’t go into details here.
Contentful mentions how GraphQL is paving the way Agile organisations
Incrementally decouple and modernize
As with many projects that venture into new territory, kicking off the initiative to build a GraphQL-based project when you’ve never done it before can be a daunting thought. But the results are worth the effort as your organization will become more modern and nimble, able to develop bigger projects more efficiently, and more responsive to changes and new technology in the long term.
The good news is that GraphQL, with its flexibility and agnostic nature that doesn’t chain itself to a specific data-layer or programming language, allows step-by-step deployment and change. This is highly beneficial for businesses, which would normally refrain from venturing into uncharted development territory and migrate everything there shortly after, by allowing an initial, smaller migration of services to working with GraphQL. Initially decoupling one or two projects from being tied down to a specific stack, language and/or database creates a great proof-of-concept for your development team’s ability to modernize everything else in your organization.
Reason 5: Tool friendly
This I read on the original Facebook post on GraphQL.
Introspective: A GraphQL server can be queried for the types it supports. This creates a powerful platform for tools and client software to build atop this information like code generation in statically typed languages, our application framework, Relay, or IDEs like GraphiQL (pictured below). GraphiQL helps developers learn and explore an API quickly without grepping the codebase or wrangling with cURL.
Astronomer in their blog talks about documentation.
Documentation and Deprecation
Moving fast and breaking things seems to be a requirement for a new company to keep innovating; however, it’s a disaster once you open up control to external applications. Anyone connecting to your API needs to know what is available and when things will change well in advance. GraphQL makes moving quickly much easier with their schema, as it will automatically build documentation from your comments.
Workday mentions GraphiQL as one of the reason why GraphQL is successful.
Another major benefit provided by GraphQL is the ease with which the API can be tested and browsed using GraphiQL. GraphiQL describes itself as a “graphical interactive in-browser GraphQL IDE.” It allows developers to easily write (with autocomplete) and issue any query, view the results, and navigate the schema via automatically generated documentation. Most GraphQL server implementations come with built-in support for GraphiQL, and it’s simple to configure and run for those that do not.
Reason 6: Version free
This I read on the original Facebook post on GraphQL.
Version free: The shape of the returned data is determined entirely by the client’s query, so servers become simpler and easy to generalize. When you’re adding new product features, additional fields can be added to the server, leaving existing clients unaffected. When you’re sunsetting older features, the corresponding server fields can be deprecated but continue to function. This gradual, backward-compatible process removes the need for an incrementing version number. We still support three years of released Facebook applications on the same version of our GraphQL API.
Reason 7: Development velocity and developer productivity
Novvum conducted a survey that said organisations are adopting GraphQL for productivity reasons.
We found that development velocity was the main reason why companies started using GraphQL, and nearly all of the companies felt GraphQL delivered on their expectations.
GraphQL is primarily designed to improve developer productivity because it lets the client decide what type of data they need and eliminates the back-and-forth communication between frontend and backend engineers. Large companies are able to use these features to their advantage to speed up and improve their development velocity.
Developer productivity — Immediately productive, without tribal knowledge. If you know JSON, you know GraphQL. Incredible tooling, too!
Reason 8: Evolution
Paypal team mentioned in their blog
Evolution — With GraphQL, API developers know exactly what fields their clients are using and are able to make better choices when deprecating or evolving their APIs. With REST, this isn’t possible so you extend and never delete.
Things to watch out for with GraphQL
API Rate limiting
File upload is not part of the specification. You have to use library like apollo-upload-server – Link
Caching is difficult
- Facebook: GraphQL: A data query language – Link
- The GitHub GraphQL API – Link
- 3 Reasons Why Astronomer is Betting on GraphQL – Link
- Shopify: GraphQL and its benefits – Link
- Implementing GraphQL at Major League Soccer – Link
- Artsy: Improving Page Speeds with GraphQL – Link
- Coursera’s journey to GraphQL – Link
- GraphQL: A success story for PayPal Checkout – Link
- Walmart Labs: Open Sourcing Lacinia, our GraphQL Library for Clojure – Link
- Real-World Reasons To Use GraphQL – Link
- Why Companies are Adopting GraphQL – Link