GraphQL vs. REST API

Have you ever worked on a web app development project before? If so, then you may have already encountered the term "GraphQL". But what exactly does it mean? Is it used in server-side or client-side configurations? Additionally, when is GraphQL integration preferable to other alternatives? In this article, we will guide you through these questions.

As a communication channel for data transfer between software components over the internet, APIs play an indispensable role in modern web service architectures, acting like oxygen. API technologies such as SOAP (a web services messaging protocol), REST (architectural style), and GraphQL (a query language and tool) facilitate software development by supporting integration and data exchange between different services, making development more convenient and flexible.

Despite the numerous types of APIs, debates in recent years have predominantly centered on two main paradigms: REST (representational state transfer) and GraphQL. Both offer a range of advantages and are used globally in web projects. However, they differ significantly in how they manage data communication.

What is REST API?#

REST is a structured architectural style developed in the early 21st century for building cross-network hypermedia applications, designed to adopt a stateless, cacheable communication protocol between clients and servers. The REST API (also known as RESTful API) is the driver of the REST architecture.

REST API uses Uniform Resource Identifiers (URIs) to address resources. REST API works by using different endpoints to perform CRUD (create, read, update, and delete) operations on network resources. It relies on predefined data formats (known as media types or MIME types) to determine the form and size of the resources they provide to clients. The most common formats are JSON and XML (sometimes HTML or plain text).

After the client requests a resource, the server processes the query and returns all data related to that resource. The response contains HTTP response codes such as "200 OK" (for a successful REST request) and "404 Not Found" (for a non-existent resource).

How does REST API work?#

REST APIs rely on predefined endpoints that expose resources over HTTP. Each endpoint represents a resource, such as users or posts, and is identified by a unique URL. REST operations are tied to standard HTTP methods like GET, POST, PUT, and DELETE, which correspond to retrieving, creating, updating, and deleting data.

For instance, a request to GET /users retrieves a complete list of users, while GET /users/123 fetches the details of a specific user identified by their ID. If you also need to access related data, such as the user's organizations and organization roles, you would need to make additional calls to the GET /users/123/organizations.

REST follows a resource-centric approach, focusing on accessing and manipulating discrete resources.

What is GraphQL?#

GraphQL is both an API type (or query language) and a runtime engine for responding to those queries. It offers a simplified API and is particularly suited for mobile applications and the implementation of complex architectures that require specific subsets of data.

With GraphQL, developers can specify the data they want to retrieve from the API. It also allows for on-demand data retrieval instead of fetching everything at once, applies changes immediately, and integrates third-party data sources into the application.

Applications can use GraphQL queries to call GraphQL services. These queries return the exact data elements requested by the client. This saves multiple API calls, network bandwidth, and post-processing. It is a highly efficient solution for data-centric APIs that are located close to consumer devices such as tablets and mobile phones.

How does GraphQL work?#

GraphQL, in contrast, takes a query-based approach. Instead of predefined endpoints, GraphQL exposes a single endpoint that accepts structured queries. Clients specify precisely what data they need using a query language.

Therefore, a complete GraphQL implementation must have two parts: schema and resolvers.

GraphQL schema#

Schemas define the types of data and their fields that can be retrieved through GraphQL queries:

For instance, suppose you have the following schema:

A client can query a user's name, email, organizations, and roles using the following query:

This query not only fetches only the requested fields (email, and organizations) but also retrieves the related data (roles) in a single request.

GraphQL resolver#

A GraphQL resolver is a key component in a GraphQL server that determines how to fetch or compute the data requested by a client in a GraphQL query. When a client sends a query, each field in the query is matched to a resolver, which contains the logic to retrieve or calculate the data for that field.

In the example above, the resolvers for the schema would look like this:

There are two types of resolvers: root resolvers and field resolvers.

• Root Resolvers: Handle top-level fields in the schema, such as Query, Mutation, and Subscription.
• Field Resolvers: Handle individual fields within a type, often for nested queries. If no specific resolver is provided for a field, GraphQL uses the default resolver, which returns the value from the parent object with the matching field name.

GraphQL operations#

GraphQL supports three types of operations: queries, mutations, and subscriptions.

• Query: Used to READ data.
• Mutation: Used to WRITE data, including operations to add, modify, and delete data.
• Subscription: Used to request a persistent connection for data, allowing the client to declare the types of events it is interested in and the data that should be returned.

Differences between GraphQL and REST APIs#

GraphQL and REST APIs are tools for exchanging data between different web services, but due to their different approaches to solving problems, here are the key differences between them:

Data fetching#

REST API often over-fetches or under-fetches data because endpoints return fixed responses. GraphQL solves this by letting clients request exactly what they need, reducing unnecessary data transfer. This makes GraphQL ideal for applications with complex data needs, such as mobile or low-bandwidth environments.

Imagine the above example where you need to fetch a user's static data, organizations and organization roles assigned to the user. With REST API, you would need to make multiple requests to different endpoints to get all the data. However, with GraphQL, you can fetch all the data in a single request.

Flexibility#

REST’s endpoint-based structure is straightforward and works well for simple applications with standard CRUD operations. This is because REST APIs are designed to be resource-centric, with each endpoint representing a specific resource. The major limitation of this approach is that it does not allow for rapid iteration and changes in client requirements. With every change made to the client, the server must be updated to accommodate the new requirements, either by adding new endpoints or updating existing ones. This often ends up in a lot of redundant endpoints and complex API version management.

GraphQL, on the other hand, is more flexible and allows clients to request only the data they need. This flexibility is particularly useful when client requirements change frequently, as it eliminates the need to modify the server-side API implementation. Clients can request new fields or nested data without requiring changes to the server.

Caching#

Even though GraphQL is more efficient and flexible in terms of data fetching, it also has some drawbacks. One of the main issues is caching.

The REST API has a mature ecosystem. Due to its stateless and standardized nature, it is easy to cache responses at both the server and client levels. This can significantly reduce the number of requests made to the server and improve performance.

However, due to its flexibility, many of the caching technologies available for the REST API are not applicable to GraphQL. It is necessary to handle caching on the client-side, based on specific use cases, which brings extra workload to client development.

Pros and Cons#

Conclusion#

Although GraphQL has gained strong momentum as a newcomer in recent years, REST API still holds significant importance for a long time due to its atomic design and rigor.

REST and GraphQL serve different needs and excel in different scenarios. REST's simplicity makes it a perfect choice for straightforward applications and microservices. GraphQL stands out in scenarios requiring flexible and efficient data retrieval, particularly in applications with diverse clients or complex relationships between data. The choice between the two depends on your project's specific requirements, team expertise, and long-term scalability needs.