GraphQL vs REST API: Pros and Cons

APIs for Modern Web and Mobile Applications API Design for Modern Distributed Systems - First Edition Every day we hear about new web and mobile applications and API design is the common theme between good web and mobile applications and bad web and mobile applications and it is API design that allows consumers to access the data. In the last decade REST has been the standard for API design. Recently we have GraphQL, a new level of API design that has adapted to modern web and mobile applications. This book provides great insights into API design standards and helps in choosing the right standard for the application.

Understanding the Fundamentals

What is REST?

REST (REpresentational State of Resource) is an architectural style for software design. The term was introduced by Roy Fielding in his 2000 doctoral dissertation titled "Architectural Styles and the Design of Network-Based Software Architectures". In REST, resources are addressed by a uniform resource locator (URL) such as an internet web page or a web page on a web site, and operations that perform modifications on resources are applied to that URL with the HTTP methods. Each API endpoint represents a resource and the response to a request is usually the full representation of that resource, often called a document.

Example REST endpoint:

GET /api/users/123
GET /api/users/123/posts
GET /api/users/123/posts/456/comments

What is GraphQL?

GraphQL is an open query language specification for any back end or data source. GraphQL was released by Facebook in October 2015 as an open source project. A query language for your API, GraphQL allows you to define types for API fields such as queries, mutations and/or subscriptions and the return types for the data. GraphQL is a data language query, like SQL, but for APIs and web applications. With GraphQL, each time a client requests data, it requests only the data it wants. Instead of requesting all of the possible data that a client might be interested in, a client can request only the data it needs, and the data source will return only the requested data.

Example GraphQL query:
graphql
query GetUserWithPosts {
user(id: 123) {
name
email
posts {
id
title
comments {
text
author
}
}
}
}

REST API: Advantages

1. Simplicity and Familiarity

REST is a very simple architecture and easy to implement. Because REST is built off of the HTTP protocol that we’ve been learning about, you’ve already been using REST and have the knowledge necessary to build a REST API. Many applications already implement REST without realizing it. Most people interact with resources and the server they connect to by creating and modifying them. This is exactly what REST is about, which makes it very easy to understand and implement.

2. Excellent Caching Mechanisms

A common mechanism for rest apis is the use of the standard http caching headers (such as ETag, Cache-Control, Last-Modified). There are a lot of advantages with rest apis. One of the big one is the possibility to use native browser caching as well as CDNs and proxy servers. They already knows the HTTP caching semantics.

3. Stateless Design

Stateless is a term used in the REST architectural pattern to describe a particular aspect of client-server communication. As we just covered, a server in a client-server system cannot remember anything from previous requests. So all information needed to process a request must be included in the request itself. This leads to a principle of statelessness that makes the construction of scalable systems using REST easier. While it is counter-intuitive at first, it has many advantages. In short, statelessness means that horizontal scaling is easy. Horizontal scaling is the term that describes the process of increasing the capacity of a system by adding more servers to the infrastructure, and which allows to distribute the workload among all the available resources in order to avoid saturating any single point, thus ensuring a more stable and reliable service. Horizontal scaling is easier when all nodes provide the same service. Load balancing between nodes is therefore much simpler in horizontal scaling.

4. Robust Tooling Ecosystem

Free and Open Source APIs require fully automated, ID-based development tools. Only then can we talk about a mature system. In this case we are referring to the programming model and the toolchain of a RESTful API. As we see in the title of this chapter, the Free API Model follows the paradigms of today’s applications programming. Following in particular today’s software development practices from test frameworks up to the monitoring stacks and standards of documentation generators. However today’s full featured Integrated Development Environments (IDEs) and build tools are not available under a free license.

5. Browser-Friendly

REST style APIs used as APIs take full advantage of the functionality that is available in a common web browser and are easy to test by simply entering the API URL into a web browser location bar.

REST API: Disadvantages

1. Over-fetching Problems

Return only structs. Easy one that someone brought to my attention. So if you try to grab $user, Laravel wants to grab and hydrate every single column of the database – whether you asked for them in $appends() or not. But if you only asked for lets say name and id, there is alot of overhead that will be incurred from database i/o, as well as on mobile battery drain and unnecessary bandwidth usage. All to be able to hydrate and discard in memory data that you never plan on using.

2. Under-fetching Requirements

API’s are designed for quick data exchange in between the systems. In case a single API call does not serve the purpose, the scenario is termed as Inverse Problem. A good example would be a Mobile application displaying User Profile Information along with a list of relevant posts and comments. In such cases, minimum 3 API Calls have to be made. We all know what a Long Latency can cause to end user.

3. Versioning Challenges

As APIs evolve, maintaining backward compatibility becomes problematic. Common solutions include:

• URL versioning (/api/v1/, /api/v2/)
• Header-based versioning
• Deprecation policies

Each approach introduces complexity and maintenance overhead.

4. Rigid Data Structure

All REST endpoints return known data structures. Requesting a different set of fields might require a change on the server.

5. Multiple Roundtrips

Today’s Applications deal with an ever increasing amount of complex data. Loading that data is not always possible in a single HTTP request. With the increasing complexity of the data, a multitude of HTTP requests have to be made. This leads to a waterfall of dependencies, longer response times and a higher server load.

GraphQL: Advantages

1. Precise Data Requirements

The client can ask for the required columns from the database and the server will return only the required columns, thus preventing the over-fetching of data which is a major issue in mobile applications due to bandwidth.

2. Single Request Solution

The most common complaint you hear from API designers is that GraphQL solves the under-fetching problem. What does that even mean? It’s actually quite simple. Your application needs to know everything it wants to display before it can ask the server for the data. There are only a handful of resources that your application will need, and having to make separate requests for each one is not only tedious but also inefficient.

graphql
query {
user(id: 123) {
name
posts {
title
comments {
text
}
}
}
}

3. Strong Type System

This folder contains some examples of how you can implement data processing in code. Each file uses the GraphQL schema which allows features like code completion, validation and documentation, making it easier to code. The GraphQL schema is an agreement between the frontend and backend teams that represents the data structure.

4. Backward Compatibility

Adding new fields to the GraphQL API does not break existing queries. Only the fields that are requested by the client are populated with data and new fields that are not requested do not cause a breaking change in the API surface. The schema is dynamic and flexible and allows for easy modification and extension without disrupting existing workflow.

5. Excellent Developer Tools

With GraphiQL and Apollo DevTools, you can dive into your API and debug your code interactively. Real-time documentation, variable completion and query validation help you work more efficiently.

6. Subscription Support

Real-time data is a crucial part of most modern web application. GraphQL subscriptions provide an elegant, easy way to get all your real-time data in one place. Without the hassle of running a Relay server and WebSockets.

GraphQL: Disadvantages

1. Increased Complexity

Let's start a new project using GraphQL. As we all know, setting up a new project is a little more complicated than setting up new traditional API. To work with GraphQL you need to know what is query, mutation, subscription, resolvers, schema definition language (SDL) and many other things in order to communicate and work with a GraphQL API.

2. Caching Difficulties

For us, the caching mechanism that HTTP uses that’s based on URL keys just doesn’t make sense. And also the majority of applications have only a single API endpoint. Even GraphQL have only a single API endpoint, the queries. But again, for HTTP caching isn’t an issue for us. Now we have to implement the caching mechanism on the application level. And that comes with few extra caveats.

javascript
// Apollo Client caching example
const cache = new InMemoryCache();
const client = new ApolloClient({ cache });

3. Query Complexity

They can input whatever they’d like into the search bar: Before we start processing anything, though, we have to make sure we won’t overload the server with crazy, nested queries or return huge result sets:

graphql

Problematic query - potential DoS

query {
user(id: 1) {
posts {
comments {
author {
posts {
comments { ... }
}
}
}
}
}
}

Implementing query complexity analysis and rate limiting is essential but adds complexity.

4. File Upload Complications

GraphQL isn’t really good at dealing with file uploads. While it is technically possible to make some work arounds for dealing with GraphQL and file uploads, it is a much more satisfactory and restful experience dealing with REST and multipart/form-data.

5. Monitoring and Debugging Challenges

All requests are routed through a single point of entry in an attempt to conceal the true nature of the application. It is extremely difficult to figure out which SQL query is the cause of any performance issues or bottlenecks in the application.

6. Server Implementation Overhead

More setup is required to build a GraphQL server. Resolvers will also need a bit more attention to avoid common database query issues like the N+1 problem, which you might already be familiar with.

Comparative Scenarios

When to Choose REST

• Simple, resource-oriented APIs: CRUD operations on well-defined entities
• High-traffic public APIs: Leverage HTTP caching effectively
• Simple clients: Browser-based applications with basic needs
• File-heavy operations: File uploads and downloads
• Team expertise: Team has strong REST knowledge and limited GraphQL experience

When to Choose GraphQL

• Complex data relationships: Applications requiring flexible data fetching
  Different types of Clients - Mobile, Web and Native Apps Different data volumes for different applications.
• Real-time requirements: Applications needing subscriptions and live updates
• Developer-first APIs: Public APIs targeting experienced developers
• Rapid iteration: Frequent schema changes without versioning pain

Hybrid Approaches

Many organizations adopt hybrid strategies:

A decision I have made for the upcoming eShopOnDuty web application. Backend + Public API architecture with a REST based public API and GraphQL for backend microservices. #eshoponduty #architectures #graphql #rest
API Gateway Use cases 1. Get the data you need from other APIs 2. GraphQL gateway over REST services: Expose REST backends through a GraphQL layer
As we move on, you'll find the rest of the free chapters in the next section. But first, here's a taste of what's coming next. — 3.0. 3. Coexisting endpoints: Serve both REST and GraphQL from the same application

Conclusion

The rest of this is largely a non-issue. There isn’t really a gain or loss by choosing REST or GraphQL. Instead, you simply choose the technology that is best for your situation. REST is a very simple technology which means that REST-based systems are easy to cache, easy to implement and easy to understand. GraphQL, on the other hand, is a bit more powerful and can handle very complex data structures. In more situations, the data flow between the client and server can be more dynamic. Again, it’s not about choosing good or bad technology. It’s more about choosing technology that fits your situation, your expertise and your place in the application stack.

Take some time to understand what each requirement means for your application. I would start by building a REST API and then gradually evolve it to leverage GraphQL as needed. Larger corporations tend to mix REST and GraphQL in their backends, so they’re not mutually exclusive.