GraphQL Vs. REST APIs: A comprehensive comparison for developers

GraphQL is gaining momentum as a successor to REST APIs. However, it isn’t always a “replacement”, and making the decision to opt for GraphQL comes with several considerations.

Traditionally and when used “out of the box”, REST has had limitations like multiple network requests and overfetching data. To overcome these, Facebook developed GraphQL as an open-source data query and manipulation language for APIs.

GraphQL is a syntax for requesting data and lets you specify precisely what you need.

Depending on your use cases, you will need to choose between GraphQL or REST API, or a combination of both. To make a more informed decision, let’s take a closer look at REST and GraphQL, the benefits of each, and what they're best used for.

#What is REST?

REST (Representational State Transfer) is an architectural style that conforms to a set of constraints when developing web services. It was introduced as a successor to SOAP APIs.

REST, or RESTful APs, are Web Service APIs that follow the REST standards. Unlike SOAP, a REST API is not constrained to an XML format and can return multiple data formats depending on what is needed. The data formats supported by REST API include JSON, XML, and YAML.

When a client calls REST APIs the server transfers the resources in a standardized representation. They work by returning information about the source that was requested - and is translated into an interpretable format.

REST APIs allow for modifications and additions from the client side to the server, drawing certain parallels with GraphQL Mutations, which we’ll cover more about.

#Working with REST APIs

A REST request consists of the endpoint, HTTP method, Header, and Body.

An endpoint contains a URI (Uniform Resource Identifier) that helps identify the resource online.

An HTTP method describes the type of request sent to the server. They are:

• GET reads a representation of a specified source.
• POST creates a new specified source.
• PUT updates/replaces every resource in a collection.
• PATCH modifies a source.
• DELETE deletes a source.

When working with data, a RESTful API uses HTTP methods to perform CRUD (Create, Read, Update, and Delete) operations.

Headers provide information to clients and servers for caching, AB Testing, authentication, and more.

The body contains information that a client wants to send to a server, such as the payload of the request.

Here is what a sample Rest API request to fetch some data from the server looks like:

// Request 
GET https://myrestapi.com/users/1

// Response
{
    "_id": "1",
    "name": "John Doe",
    "username": "johndoe",
    "email": "johndoe@gmail.com",
    "currentJobTitle": "Software Engineer",
    "phone": "9876543210",
    "gender": "MALE",
    "country": "Germany",
    "display_picture": "8ba58af0-1212-4938-8b4a-t3m9c4371952",
    "phone_verified": true,
    "email_verified": true,
    "_created_at": "2024-05-06T13:11:41Z",
    "_updated_at": "2024-05-08T13:11:41Z",
    "_deleted": false
}

#What is GraphQL?

GraphQL is an open-source data query and manipulation language for APIs. It's a runtime for fulfilling queries with existing data. Maintained and developed primarily via the GraphQL Foundation, GraphQL has incredible adoption across a variety of verticals and use cases with organizations like Twitter, Expedia, Shopify, and Hygraph to name a few.

To get into the details of GraphQL, refer to our GraphQL academy.

Here is an example of GraphQL request response:

// Request 
POST https://mygraphqlapi.com/

// Request Body
query getAllUsers($userId: string){
  userByUserId(userId:$userId){
    name
    email
    currentJobTitle
  }
}

// Response
{
    "name": "John Doe",
    "email": "johndoe@gmail.com",
    "currentJobTitle": "Software Engineer",
}

#Advantages of GraphQL APIs

Let’s cover some of the basic advantages that help GraphQL stand out.

Data Fetching

One of the most common limitations of REST is over- and under-fetching. This happens because the only way for a client to download data is by hitting endpoints that return fixed data sets. It’s very difficult to design the API to provide clients with their exact data needs.

Overfetching means getting more information than you need. For example, if the endpoint holds data on burgers available at a restaurant, you’d hit the /burgers endpoint, and instead of only getting the names that you’re interested in, you may get everything that endpoint has to offer - including price, ingredients, calories, etc. With GraphQL, you’d simply need to dictate what you want in a query:

{
  burgers {
    name
  }
}

Your response wouldn’t include any other information that the endpoint may be able to provide, giving you a predictable dataset to work with based on what you requested.

Schema and Type Safety

GraphQL uses a strongly typed system to define an API's capabilities. All the types exposed in an API are written down in a schema using the GraphQL Schema Definition Language (SDL) and/or code-first.

Frontend teams can now work with the typed GraphQL API, knowing that if any changes occur from the backend team on the API's design, they’ll get this instant feedback when querying it from the frontend.

Popular tools like the GraphQL Code Generator can automatically build all of the code for queries, and mutations, directly from your codebase GraphQL query files. This speeds up development and prevents errors in production.

Rapid Product Development

A common pattern with REST APIs is to structure the endpoints according to the views inside your app (e.g., /menu, /prices, /images, etc.). This is handy because it allows the client to get all required information for a particular view by simply accessing the corresponding endpoint.

This approach's drawback is that it doesn’t allow for rapid iterations. With every change to the UI, there is a risk of more (or less) data being required than before.

Consequently, the backend needs to be adjusted to factor in those new data needs, which is counterproductive and slows down the process of product development.

With GraphQL's flexible nature, changes on the client side can be made without any extra work on the server. Since clients can specify their exact data requirements, no backend adjustments need to be made when the design and data needs on the front end change.

Schema Stitching

A major differentiation is the ability for stitching schemas. GraphQL can combine multiple schemas into a single schema to make it accessible to the client. For example, merging the schemas of a Burgers API and a Nutrition API by getting the details of a particular menu and the nutrition facts of the item into a single schema from different sources.

{
  burgers(where: { name: "cheeseburger"})
  # from Menu endpoint
  name 
  description 
  price 
  # from Nutrition endpoint
  calories 
  carbohydrates  
  # from Restaurant endpoint
  inStock 
}

At Hygraph, the next step from Schema Stitching is the ability to federate GraphQL and REST APIs into a single GraphQL endpoint. To learn more about applying Content Federation in production, get in touch!

#GraphQL vs. REST

The core difference between GraphQL and REST APIs is that GraphQL is a specification, a query language, while REST is an architectural concept for network-based software.

GraphQL is great for being strongly typed and self-documented based on schema types and descriptions. It integrates with code generator tools to reduce development time.

When thinking of one of the most known differentiations - the differences in expected responses for queries - in very simple terms, we can think of the process of ordering burgers. While the GraphQL burger meme has been around for some time, its clarification still makes it simple to grasp the concepts.

Imagine you’re walking into a burger restaurant, and you order their cheeseburger. Regardless of how many times you order (calling your RESTful API), you get every ingredient in that double cheeseburger every time. It will always be the same shape and size (what’s returned in a RESTful response).

https://api.com/cheeseburger/

With GraphQL, you can “have it your way” by describing exactly how you want that cheeseburger to be. You can now have your cheeseburger (response) as a bun on top, followed by a patty, pickle, onion, and cheese (unless you’re vegan), without a bottom bun.

query getCheeseburger ($vegan: Boolean) {
  cheeseburger {
    bun
    patty
    pickle
    onion
    cheese @skip(if: $vegan)
  }
}

Your GraphQL response is shaped and sized exactly as you describe it. It is exactly what you wanted or queried—no more, no less, no different.

A REST API is an "architectural concept" for network-based software. GraphQL, on the other hand, is a query language and a set of tools that operate over a single endpoint. In addition, over the last few years, REST has been used to create new APIs, while the focus of GraphQL has been optimizing for performance and flexibility.

When using REST, you’d likely get a response of complete "datasets". To request information from x objects, you’d need to perform x REST API requests. If you're requesting information on a product for a menu website, your requests may be structured in this way:

• Request menu for burger names, descriptions, ingredients, etc. in one request
• Request prices for prices pertaining to that menu in another request
• Request images for menu shots from another dataset
• ... and so on

Conversely, if you wanted to gather some information from a specific endpoint, you couldn’t limit the fields that the REST API returns, you’ll always get a complete data set - or over fetching - when using REST APIs out of the box without added configurations.

GraphQL uses its query language to tailor the request to exactly what you need, from multiple objects to specific fields within each entity. GraphQL would take x endpoint, which can do a lot with that information, but you have to tell it what you want first.

Using the same example, the request would simply be to get menuItem, menuIngredients, menuImage, and menuPrice from the same endpoint, within one request, and no more. All other content within the database wouldn't be returned, so the issue of overfetching wouldn't be a concern.

This is very similar to the burger analogy we highlighted before—REST gets you the cheeseburger that the restaurant has on the menu, but GraphQL lets you modify that burger to get exactly how much of what you want.

Opting for GraphQL against or with REST is a highly subjective decision, heavily influenced by the use-case. It is important not to consider GraphQL as an alternative to REST, nor as a replacement. To help simplify that decision, here are some key differentiators:

#When to use GraphQL and REST APIs?

To put it simply, the use of GraphQL or REST APIs will depend on your application needs and the familiarity of your team.

REST can be considered if your data comes from a single data source, data requirements on the client side are pretty simple and would not constantly change.

GraphQL is preferable for applications with complex and changing data requirements, it also comes with many good features like single endpoint, client-driven data fetching, type safety, and subscription support out of the box. In the long run, these features will add great value by enhancing developer productivity and speed up product development iterations. However, if the team doesn’t have experience with GraphQL, it would have an additional learning curve.

#Wrapping up

Throughout this article, we understood the concept of both REST and GraphQL APIs, looking at what makes each unique and useful.

REST APIs have different HTTP methods, and endpoints and support data formats like JSON, XML, and YAML. However, they can have issues like overfetching and needing multiple network requests.

GraphQL solves these problems by letting clients request only the data they need, reducing overfetching and underfetching. It uses a strongly typed system defined in a schema, supports combining multiple schemas into one, and allows for real-time updates, making development faster and more efficient.

The choice between REST, GraphQL, or a mix of both should depend on your project's specific needs and your team’s expertise.