Phase 2: APIs & Databases

When GraphQL fits better than REST

Intermediate ~2 min read
Think of it this way A friendly analogy. Read this if the technical version feels dense. Show Hide

Imagine you’re ordering food from a restaurant. Sometimes, when you pick something from the menu, like a "Burger Meal," you get a whole tray of things: a burger, fries, a drink, but maybe also a toy, a small salad you don’t like, and a packet of weird sauce you'll never use. That's a bit like how some computer programs talk to each other to get information. They might ask for "all the details about a friend," and get everything – their name, age, favourite colour, shoe size, and what they had for breakfast – even if you only wanted their name and age. This is like getting too much extra stuff you don't need, making the "food delivery" (or information transfer) slower because there's so much junk to carry.

Other times, it’s the opposite problem. You ask for just a "Burger." Then you realize you also wanted fries, so you have to go back to the counter and ask again. Then you remember you wanted a drink, so you make a third trip. This is like when a program has to make many separate requests to get all the pieces of information it needs, one by one. Each trip back and forth takes time, especially if the "restaurant" (the computer server) is far away, like across the internet.

This is where a clever way of asking for information called GraphQL comes in. Instead of picking a fixed "meal" or making many small requests, you get to write your own super-specific order form. You tell the kitchen exactly what you want: "I'd like a burger with cheese, fries, and a lemonade, please. No toy, no salad, no weird sauce." With GraphQL, you can tell the computer program, "Give me only my friend's name and age, nothing else." It's like a magical menu where you custom-design your perfect order every single time, and it all comes in one go.

So, when you're building an app for phones or tablets, and you want it to be super speedy and not use up all your internet data, GraphQL is fantastic. It means your app only asks for the exact information it needs, making it quicker to load and smoother to use, because there's no wasted time carrying extra stuff or making multiple trips back and forth. You get precisely what you want, fast!

When considering GraphQL for your backend, its primary advantage over REST shines brightest in scenarios where clients need highly flexible and precise data fetching. With traditional REST APIs, you often encounter "over-fetching" (receiving more data than you need, like an entire User object when you only want their name and email) or "under-fetching" (needing to make multiple requests to different endpoints to gather all related data, e.g., fetching a Post, then its Author, then the Author's Bio). GraphQL elegantly solves this by allowing clients to specify exactly the data shape and fields they require in a single request. This drastically reduces network payload sizes and round trips, leading to improved performance, especially for mobile applications or clients with unstable network conditions.

Beyond efficient data fetching, GraphQL truly excels in complex application architectures, particularly those built with microservices. Instead of clients needing to know about and interact with multiple distinct REST endpoints from various services, a GraphQL server can act as a powerful API gateway. It aggregates data from different underlying services (e.g., one service for user data, another for product information, and a third for order history) and presents a single, unified graph to the client. This simplifies client-side data management, abstracts away backend complexities, and allows frontend teams to iterate much faster. They can build new features requiring data from multiple sources without waiting for new custom REST endpoints to be developed, fostering greater frontend agility.

Ultimately, GraphQL is a strong contender when your application features a dynamic and evolving client-side experience that demands tailored data. This includes sophisticated dashboards, highly interactive UIs, or any application where the client's data needs are diverse and not easily mapped to a fixed set of REST resources. It empowers clients to drive their data requirements, leading to more efficient data transfer, simplified client code, and a more maintainable API layer for growing and changing applications, making it ideal for scalable backend solutions.

Key Takeaways

  • Eliminates over-fetching and under-fetching by enabling precise data requests.
  • Unifies multiple backend services into a single, client-friendly API endpoint.
  • Empowers frontend teams with greater autonomy, leading to faster development cycles.
  • Improves performance and reduces network overhead, especially beneficial for mobile clients.

Code Example

graphql
query GetUserProfileAndPosts($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
    posts {
      id
      title
      createdAt
    }
  }
}

How this code works

This GraphQL query is designed to fetch a specific user's complete profile information along with all the blog posts they have authored, all in a single request. This ability to retrieve a user and their related posts together exemplifies how GraphQL efficiently handles interconnected data, often requiring multiple separate requests in a RESTful approach. The query begins by declaring query GetUserProfileAndPosts($userId: ID!), naming the operation GetUserProfileAndPosts and defining a required (!) input variable $userId of type ID. This variable allows the query to be reused to fetch data for any user by simply providing their ID.

Inside the query, user(id: $userId) is the primary field, telling the server to locate a user based on the provided $userId. Nested within this user field are id, name, and email, specifying exactly which profile details to retrieve. The crucial part for handling related data is the posts field nested directly underneath user. This instructs the server to not only fetch the user's core data but also to automatically include all posts associated with that user. For each post, it then specifies the id, title, and createdAt fields. A subtle but powerful aspect here is that because posts is nested, the GraphQL server automatically understands the relationship between the user and their posts, handling the fetching of all related posts in the same request without needing separate calls or explicit join logic from the client.

Resources

Related Articles

Hand-picked reads to go deeper on graphql.

Back to Backend Developer Roadmap