GraphQL, other than being one of the hot, relatively new buzzwords in web development, is a technology that has a lot of practical business applications. But it’s a lot easier for software engineers to understand it than business stakeholders.
Technical people have been adopting it for a number of reasons; but what about the non-technical business folks? If you’re wondering why (or whether) you should adopt GraphQL in your organization (or whether you should), this article is for you.
If you already know what GraphQL is, skip to the next section. For those that need a primer, GraphQL is a methodology for interacting with databases. The “QL” stands for “Query Language, ” which is accurate; GraphQL is a language for querying backend systems from an application that is more robust and lean than conventional APIs, but much simpler and safer than directly interacting with the database via SQL.
In some ways, GraphQL is thought of as an evolution upon other ways of constructing APIs for web applications for communicating with their backends. We’ll go into some of these reasons in the next section.
REST APIs are great and have become the standard for over a decade. REST was a natural evolution past its predecessor, SOAP, and solved a lot of challenges that were commonly present in SOAP APIs. REST is very commonplace and quite mature now, and while it’s very strong at doing some things, naturally it has its own limitations as well. GraphQL’s strength — among others — is addressing a number of these weaknesses.
Sometimes you want your app to retrieve a list of products with all their details (different photos, technical specs, and dimensions); sometimes you want only basic info like the product name and thumbnail image.
With REST, this means doing things that can get messy; creating random parameters to your /products API call that tells it which data to bring back, or creating ad hoc API endpoints like /products/basic and /products/detailed. This bloats your codebase and can get messy as it scales.
Then let’s say you want to get a list of product collections with all the products associated with each. Either you’d do something like the solution above (make /collections return all product details along with the list of collections), or if you’re trying to keep your “resources” separate, you’d make one API call to /collections and another to /products, then mash the data together in the app. In either case, you’re slowing things down (the second case more so, since two API requests will be slower than a single, fatter API request). Both situations work, but neither is ideal.
With REST APIs, to update a single endpoint you have to duplicate the API structure, add a v2 (or v3, v4, etc) prefix to the URL path and reproduce each endpoint. Using the example above, this means creating /v2/products, /v2/collections and so on. Then the apps themselves need to be upgraded to point to these new URLs.
One of the benefits of GraphQL over traditional REST is that it helps you retrieve exactly the data you want; nothing more, nothing less.
Using the example above, your collections page in the app could be retrieved by a single GraphQL query that says, “Give me only the product collections I want, only the products I care about in those collections, and only the product information I want.” And if you have different places in the app that require different details for products or collections, I can define another query that also gives me exactly the data I need for each particular screen.
Based on the above, you can hopefully understand that building an API using GraphQL is very efficient; efficiency lends itself well to speed, which means your customers are waiting around collectively less. Speed is highly correlated with better software engagement since customers aren’t waiting around for requests to complete. For websites and apps, it’s also a major factor in SEO. And both SEO and customer engagement contribute directly to revenue and company perception. Faster apps mean better business.
There are a lot of cases in which, after some initial setup, developers can engineer features in GraphQL quicker than they would against traditional REST APIs. Once a REST API is established and there are app features making requests against its endpoints, those existing endpoints can’t be refactored easily without the risk of breaking the existing features or having to add new API endpoints ad nauseam.
Alternatively, a REST API can be versioned; that is, if the app is working against version 1.0 of the API, a version 2.0 can be built and the app can gradually be adjusted to work against it. However, that can be a slow process, and if rushed it could mean the app gets messy since it might be using both versions of the API at once.
With GraphQL, you can add new features as quickly or slowly as you need to, without worrying about backward compatibility. Since GraphQL’s query resolvers aren’t dependent on each other, you can add new ones without breaking anything. So say goodbye to the notion of having to version an entire API just to make improvements to existing features.
In software development, strong typing (a feature of some programming languages) is a way of enforcing that a piece of changeable data will always be of a certain type. If I define a bucket that only numbers can go into (as opposed to text, or true/false values), then that bucket will contain only numbers; I’ll never expect a number and get something else. This essentially eliminates the possibility of an array of software bugs that result from expecting one type of information and getting another.
Similarly (though not quite the same as strong typing), GraphQL provides typed API data. When you define your GraphQL schema, you can declare that a User query will return a User that has an id, first name, last name, and email. That same User definition can potentially be used in your mobile or web app’s codebase, which means that when your app pulls data from GraphQL, it’s going to get what it expects (e.g., a number for id, and text for first/last name) — this is especially transparent if you’re using a type system like TypeScript in your app. The more you can control typing in your application and API, the more stable your software will be in general.
Because of the popularity of GraphQL, a rich array of developer tools have gained adoption which makes GraphQL not only easier to work with, scale and maintain, but more enjoyable to work with as well. GraphiQL and GraphQL Playground let developers work easily with their data and see the structure of their APIs at a glance; Prisma makes creating a GraphQL API even easier and very performant; GraphQL-tools helps developers generate and test their schemas appropriately; Apollo Server is phenomenal, and there are plenty more. @matt has a great post talking about the technical details of a number of great tools out there. And in general, more tools like this for each developer task means easier, faster, and more enjoyable development.
Because GraphQL allows developers to pull complex combinations of data, implementation can be faster than with REST or other API architectures; rather than pulling your data from two or more places and joining it together, you pull it from one place.
Adding to that, the self-documenting nature of GraphQL means less time spent writing and adjusting documentation; the docs are already done the minute you write the code. And while using GraphiQL or GraphQL Playground developers can read the docs easily alongside their query code as they’re writing it.
The combination of small things like these adds up to one thing: more developer time getting freed up to allocate toward growing and improving your application.
Versioning in GraphQL is by default backward compatible, with fewer updates required. For example, to allow apps to pull an `avatar_image` field from the `/products` endpoint, no duplication of the API structure is needed, and no version number needs to be added to the path. You simply enable the new field to the `products` portion of the schema, and apps can retrieve it at will. It’s automatically backward compatible, and you can remove any old fields at your leisure.
This not only reduces development work even more since less API work is required to add features, but it reduces redundant functionality (since there’s a need to duplicate a whole API structure). It also means your API requests stay lean; since the GraphQL endpoint doesn’t automatically send back any old data for backward compatibility, new versions of the app are still only getting exactly the data they need and nothing more.
All of the above are perks of using GraphQL itself as a way of querying your data over HTTP. By using Apollo Server, you get a number of other benefits that fit into a wide array of development projects and existing architectures.
Adopting new web services can sometimes mean rewriting old client and server code, and introducing the risk of breaking things. Apollo lets you run GraphQL on top of your existing APIs, whether they be REST, SOAP or anything else. In addition, it doesn’t matter what web server (or serverless) setup you’re using either; Apollo has integrations for Express, Restify, Microsoft Azure, AWS Lambda, and just about every setup you can think of. It also can be run by itself if you choose to go that route.
What this means: not only is it going to work well with what you’ve already got, but you can adopt it incrementally and gradually. Once you setup Apollo Server and add Apollo Client to your app, you can choose to have one feature use it, two features, or a dozen. Only use it for new features, or gradually port old ones to it. Leave the old ones running against the existing APIs for as long as it makes sense for your team and your business. You have full control.
With Apollo Server, you can now cache your API queries on a far more granular level than with typical REST or any other API format. Instead of either caching or not caching users and blog posts, you can decide to cache users and blog posts selectively based on criteria like how often their content is viewed.
This means a large speed boost right out of the box if you don’t have caching already; if you do, it means caching anything that doesn’t need to change as often and making the specific data that changes often refresh at will. Just like the way GraphQL allows you to query your data, Apollo allows you to cache it in a way that is much more exact than before possible. The net result: speed, and a great handle on it.
Hopefully, this article gives a robust introduction to the business value GraphQL brings to the table. It’s worth noting that adopting new technology like this doesn’t necessarily come with some upfront time and learning investment since it’s a new paradigm and toolset for many. And the setup of Apollo Server and Apollo Client takes a non-trivial amount of work. But that upfront investment is worth it for a great many use cases and extremely minimal for experienced engineers. I highly recommend looking into how GraphQL and Apollo Server might be a fit for your team’s technical goals.
Mike Cavaliere is a Senior Engineering Strategist at Echobind. He’s been working with web and mobile software for two decades as an engineer, manager, and one-time CTO. He’s written dozens of articles, been on a number of podcasts, and authored a book entitled Cut into the Jamstack: Build and Deploy a Full-Stack Application Using React and Next.js. He’s a parent of two boys, loves travel, cocktails, comedy, and most music, with a special place in his heart for 1990’s hip-hop.