Today I was reflecting on an interview I had last year where the interviewer said “At your last company, you used GraphQL. I’m surprised that you didn’t use REST APIs.” If I can be really transparent and vulnerable with you all here, I was caught off guard because I honestly didn’t know they were alternatives to each other. For one, while I worked on many backend tickets, the only times I interacted with GraphQL was when 1) I was on-call and got a ticket that said the system was fetching a particular data point too often when a user clicked a button and 2) when I was working on a feature ticket that improved way users canceled subscriptions.

Now that I’ve explain how I used it, it makes sense that they are alternatives to each other. However, before working on the first ticket, I looked up “GraphQL” and just saw that it was a query language. I just thought “Cool. Query language. Kind of like SQL (which we also used).” I learned the syntax for GraphQL. I finished the tickets by changing the way we canceled subscriptions and the way we fetched data by changing the queries. Bing, bang, boom, done.

Now that I’m talking about it, I feel so silly. In one ticket, I’m fetching data. On the other, I’m deleting data. That is exactly what REST APIs do. Why didn’t I see it before?

If you’re totally lost, that’s ok! Let’s break it down together.

What does REST stand for?

REST stands for Representational State Transfer. What is that? It’s an architectural style that has standards for how systems communicate with each other. These systems could be web services or clients. For example, you might use a mobile banking app that uses REST to communicate with the bank’s services. Microservices also interact with each other through REST (these things could be done with GraphQL also but we’ll get to that later).

What is an API?

An API, which stands for Application Program Interface, is a mechanism that enables an application or service access to a resource with another service. Which doesn’t sound that different than Representational State Transfer but maybe we’ll have to put those things together.

What is a REST API and how does it work?

REST APIs communicate through HTTP requests to perform standard database functions like creating, reading, updating, and deleting records (you might know this as CRUD) within a resource.

What is GraphQL?

GraphQL is a query language developed by Facebook that provides a more flexible approach to interacting with APIs. Rather than hitting multiple endpoints or receiving more data than you need (as can happen with REST), GraphQL allows the client (or frontend) to specify the exact data it wants, all in one request. It can fetch data from multiple sources and present it in a unified response.

So like, say I have a database table that includes all the movies released in the past 50 years, their title, the year they came out, and their ratings from the critics and ratings from the viewers, number of awards won, main character, production budget, age rating, box office earnings, etc. If I want to fetch this data and render it on the frontend but I only want the movies released between 2000 and 2005 that were loved by critics but hated by the audience and I only want their title and year of release, I could use a GraphQL query to fetch that specific data.

How are GraphQL and REST API related??

Now that we know what GraphQL and REST APIs are, how are they related and why did my interview speak of them in the same sentence? The key similarity is that they are used to fetch data and help the client interact with APIs. A software engineer might use one versus the other based on how they want to fetch data. GraphQL has been said to be used instead of REST API if we want to avoid over-fetching data.

In that example before, if I wanted to fetch the data from movies table in the database but I only wanted those released between 2000 and 2005 that were loved by critics but hated by the audience, if I was using REST API, I would either need a specially designed endpoint for this filter, or I would use query parameters to filter the results. While REST APIs can absolutely handle filtered queries, GraphQL provides more flexibility in how you request the data. With GraphQL, you can filter the results AND also specify exactly which fields you want returned for each movie, all in a single query. This helps prevent over-fetching both in terms of the number of records and the fields within each record. For example, if I only need the title and year for these filtered movies, I can specify just those fields in your GraphQL query, while a REST API typically returns all fields for each movie record including unnecessary data like production budget or box office earnings.

What do GraphQL and REST API have in common?

• Purpose: Both GraphQL and REST are designed to help clients interact with APIs. They enable data retrieval and manipulation, allowing developers to build applications that consume backend services.

• Client-Server Architecture: Both adhere to a client-server architecture, where the client requests data from a server, which processes the request and sends back the appropriate response.

• HTTP Protocol: They both typically use HTTP as the communication protocol, allowing developers to leverage standard web technologies.

• Resource Representation: Both methods focus on resource representation. REST APIs expose resources via endpoints, while GraphQL provides a schema that defines the types and relationships between resources.

• Versioning: In practice, both approaches can struggle with versioning. REST APIs often require creating new versions for changes, while GraphQL aims to be more flexible by allowing clients to request only the data they need, reducing the need for versioning.

How are they different?

• REST APIs often return entire objects of data. For example, if you ask for user details, you might get the user’s name, address, and phone number, even if you only needed the name. This can lead to over-fetching of data.

• GraphQL addresses this by letting the client specify exactly what fields it wants, avoiding the problem of over-fetching. You can think of it as ordering exactly what you want from a menu instead of having to take the whole meal.

Why might you use one over the other?

• REST APIs are simple, widely used, and great for applications that need well-defined, resource-based endpoints.

• GraphQL, on the other hand, is preferred when you need more flexibility and efficiency in fetching data, especially in applications with complex data structures or multiple data sources.

What are other alternatives?

I won’t go into too much detail but alternatives to both GraphQL and REST APIs are AJAX, WebSockets, and WebRTC. This blog post describes REST APIs and GraphQL as well as Websockets, Server-Sent Events, WebRTC, gRPC, Axios, and Fetch APIs all as alternatives to AJAX (although from my understanding AJAX applications now typically utilize Fetch APIs as opposed to XMLHttpRequests to fetch data.

Conclusion

When it comes to choosing between GraphQL and REST APIs, there's no one-size-fits-all answer. Both have their strengths and use cases, and understanding them allows developers to make informed decisions based on the needs of their projects. REST APIs provide simplicity and are widely adopted, making them great for well-structured, resource-based applications. On the other hand, GraphQL offers more flexibility and precision, especially when working with complex data from multiple sources or when you want to avoid over-fetching.

As I reflect on that interview, I now see how valuable it is to understand these technologies not just as isolated tools but as alternatives that solve similar problems in different ways. Whether you're fetching data via REST or GraphQL, or even exploring alternatives like WebSockets or AJAX, it’s about choosing the right tool for the job.

Ultimately, being adaptable and open to learning is key in software engineering, and it's okay to not have all the answers right away—what matters is how we grow and evolve in our understanding. So whether you’re using REST, GraphQL, or any other tool, the important thing is knowing when to use which one and why.