The US software engineering industry revolves around efficient data transmission between computing parties. Regardless if you are creating a fintech application in the Big Apple, a microservices-based ecosystem for the next enterprise giant in the Austin city limits, or a mobile application from the heart of Silicon Valley, there are limits to the speed of your application defined by data delivery boundaries. For years, REST architecture has been the de facto industry workhorse for delivering data over the web. But with ever-increasing scaling requirements for data delivery, another solution emerged: GraphQL.

The decision between REST and GraphQL is among the most important architectural choices made by any development team. This choice affects everything about frontend performance, network efficiency, server memory footprint, and long-term cloud computing costs. If you truly want to get behind which technology makes sense for your product, you should forget about industry buzzwords and focus on how these two approaches actually load data, cache data boundaries, and adapt to evolving systems.

1. Basic Architectural Principles

Perhaps the first and foremost difference between REST and GraphQL technologies lies in the way they organize their data architectures. REST is based on the notion of unique data resources accessible through the HTTP protocol. In REST, backend servers expose structured collections of rigid, stateless URLs called endpoints. Each endpoint represents an explicit business noun, and the application executes standard HTTP verbs to interact with that endpoint (GET, POST, PUT, DELETE).

REST:

Client -> GET /api/v1/users -> Returns fixed User JSON

Client -> GET /api/v1/posts -> Returns fixed Post JSON

GraphQL technology, originally developed at Meta, takes the concept of web-based data handling one step further by shifting away from the idea of data resources towards a data graph architecture. The main point of this technology is to expose a central, singularly accessible endpoint (usually, /graphql) that processes data query documents sent over a POST HTTP command. GraphQL doesn’t define the return JSON payload format for its endpoints in advance – instead, the client specifies exactly what type of JSON object it expects to receive in the body of its HTTP request.

2. The Problem of Over-Fetching and Under-Fetching

Both frontend engineers working in a traditional REST-based framework are well-aware of these two major issues when working with REST: Over-fetching and under-fetching.

Over-fetching happens when the client application makes a request to an API endpoint, trying to retrieve only a couple of business metrics. But because each REST endpoint has a fixed response schema, the client receives a massive data payload from the backend server filled with dozens of extra irrelevant fields. So if, for example, a mobile dashboard needs to show a user’s username and avatar_url, the REST-based implementation may require the device to load an extensive set of unrelated data, such as the user’s full history, phone numbers, billing records, etc.

On the other hand, under-fetching refers to a scenario where each of a series of REST endpoints does not possess enough contextual information to form a complete frontend view. So when a mobile app wants to generate a social feed card representing a blog post and author information together with comments, the following REST-based implementation could be required:

GET /api/posts/1 -> Gets post content and an author id.

GET /api/users/123 -> Gets author display name by his/her id.

GET /api/posts/1/comments -> Gets comment threads of the post.

As you can see, both of these REST problems don’t exist in the GraphQL ecosystem. First, over-fetching is handled effortlessly as a client can send a very clear data requirement specification to a GraphQL server with a request to return exactly the type of JSON object it wants to receive. Second, under-fetching is avoided automatically thanks to GraphQL nesting feature which lets a developer write a single query document capable of extracting all needed information in one single POST network call.

3. Caching

One of the most important components of large-scale web applications is edge network caching – the process of storing frequently requested data objects close to client applications, so that no data is pulled from origin servers twice. Unfortunately, this area belongs to the clear-cut advantages of REST technologies. That is why caching should be considered before choosing the REST or GraphQL approach.

Thanks to the fact that each REST endpoint represents an explicit URL with its own unique ID and purpose, it becomes possible to identify those endpoints as independent entities that are easy to cache at the network edge with the help of standard browser and CDN mechanisms. As soon as the client application sends a GET request for a particular REST API endpoint with a unique URI, edge servers will automatically store it in their cache based on HTTP response parameters (Cache-Control, ETags, etc.).

But GraphQL doesn’t allow such convenient caching practices natively. Since all operations – including queries and mutations – take place over one singular POST command to /graphql endpoint, traditional HTTP web caches will be unable to recognize them and provide caching assistance. Moreover, the absence of GET endpoints makes all queries impossible to cache using traditional CDNs (CloudFlare, Akamai). This challenge can be addressed either with the help of custom application layer cache mechanisms such as Apollo Client, or via advanced cloud-edge solutions like APQ.

4. Type Safety, Documentation, and API Versioning

The evolution of software products leads to frequent structural transformations that are often hard to document and track across the engineering teams. While REST doesn’t natively address some of the challenges faced in modern development, GraphQL has built-in mechanisms for solving those problems.

Firstly, REST technology doesn’t offer any native validation and restriction mechanism. Thus, it is necessary for the developer to maintain external documentation files describing all endpoints of the API using OpenAPI (formerly known as Swagger) specification. And when it comes to schema modification, REST forces its teams to use explicit version tagging directly in URI (e.g. moving from /api/v1/ to /api/v2/). Of course, while being predictable, this option requires maintaining multiple versioned code branches and supporting backwards compatibility.

REST Versioning:

/api/v1/users -> Maintained for old mobile apps

/api/v2/users -> Current active version with updated schemas

GraphQL Evolution:

/graphql -> Single endpoint that evolves by declaring deprecated field names

But thanks to the strict contract-oriented architecture of GraphQL technologies, its API becomes self-explanatory. Indeed, this architecture introduces an SDL (Schema Definition Language) allowing engineers to create a strict type-safe schema for any API – thus making it possible to write automated tests against GraphQL endpoints. Moreover, tools such as GraphiQL let developers inspect, modify, and validate GraphQL APIs in real time.

As opposed to REST, versioning isn’t a problem here, as GraphQL is a type-safe architecture. Whenever some fields in GraphQL become deprecated, developers can mark them with special @deprecated directive and let old builds download them. Meanwhile, the current development builds will know not to use outdated fields and rely on newly introduced ones instead.

Finally Choice: When to choose REST vs. GraphQL?

Use REST architecture when:

Your application relies heavily on the data resources pattern and features relatively flat data models with no dense nested relationships between entities.

HTTP edge caching at global CDNs such as CloudFlare and Akamai is crucial to the scalability of your platform, which means that you need a traditional REST API with multiple GET endpoints.

You need to develop a public API for external consumers who already have experience with standard REST-based APIs and HTTP request methods.

Use GraphQL architecture when:

You work with complex frontend products such as social networks, project management dashboards, or extensive e-commerce web applications featuring multi-layered data relationships.

The primary target of your application is mobile users with limited cellular network bandwidth, where over-fetched data and round trips to origin servers is unacceptable.

You need rapid frontend iterations in your application stack where changing UI views is possible without backend engineers’ approval.

Frequently Asked Questions (FAQ)

Is GraphQL faster than REST API?

GraphQL API isn’t faster than the traditional REST one as it depends entirely on the actual architecture and configuration of your application. Although it lets clients pull down several nested relationships of an API at once, making frontend loads appear much quicker, GraphQL may slow down the server parsing of complex queries considerably, requiring extra computational resources compared to simple REST endpoint calls.

What is a GraphQL Mutation?

In a REST API, modifying state records involves interacting with corresponding endpoints using HTTP requests, e.g., POST to create new records, PUT/PATCH to update, and DELETE to delete existing ones. In GraphQL, all write, update, and deletion operations are represented by one type of action called Mutation. They are declared in the GraphQL schema explicitly and allow sending parameters in order to mutate data and query new results.

What is the N+1 problem?

N+1 problem is a common performance bottleneck of the backend server caused by poor data relationship resolution. For example, if a client application requests a collection of 100 blog posts together with their author names (which are stored separately), an inefficient backend resolver will first query all posts and then execute additional 100 queries to get each author. Such inefficiency can be solved using batching and caching libraries like Facebook’s DataLoader.

Can a single backend application support both REST and GraphQL?

Sure, why not? This practice is popular among large enterprises and involves running microservices with REST API for receiving public traffic, system logging, and binary file transfers. At the same time, the same application can have a separate REST gateway responsible for powering GraphQL-based frontend interfaces and mobile apps.

How to secure GraphQL endpoints?

One of the risks of working with GraphQL APIs consists of the ability of the client to define arbitrary data fetching requests in its payload. Therefore, attackers may exploit unsecured GraphQL endpoints using recursively defined queries causing backend database to hang and leading to application layer DoS attacks. To avoid this, security teams apply various restrictions to GraphQL queries using such concepts as max-depth, complexity, or white listing.