What Is GraphQL?

Let's Start with a Question

Have you ever built a mobile app that needed to show a user's profile?

We're guessing the answer is yes, or at least you can imagine what that would involve. You'd need the user's name, their profile picture, and maybe their latest posts. Simple enough, right?

Now, let's think about how you'd actually get that data. With most APIs today, you'd probably start with something like GET /users/123. What do you think comes back?

{
  "id": 123,
  "name": "Sarah Chen",
  "email": "[email protected]",
  "avatar": "profile.jpg",
  "phone": "+1-555-0123",
  "address": "123 Main St, San Francisco, CA",
  "birthdate": "1990-05-15",
  "preferences": { "theme": "dark", "notifications": true },
  "last_login": "2023-01-01T10:30:00Z",
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

Interesting, isn't it? You asked for user data, and you got user data. But here's the key question: Do you actually need all of that information?

Your mobile app only wants the name and avatar. Everything else - the phone number, address, preferences - is just extra baggage. You're downloading and processing data you'll never use. We call this over-fetching.

But wait, there's more. What happens when you also want to show the user's recent posts on that profile screen?

You're thinking "another API call," aren't you? That's exactly right. GET /users/123/posts. And if you want to show a few comments on each post? That's potentially dozens more API calls.

Can you see where this is heading? Your simple profile screen is now making 10+ requests to your server just to display some basic information. This is what we call under-fetching - not getting enough data in each request.

Think about your users for a moment. They're waiting for your app to load while you're making all these API calls. If they're on a slow mobile connection, they might give up and close your app. There has to be a better way, right?

What if we told you there was a solution that could get all the data you need in a single request, with only the fields you actually want? Before we dive into this solution, you might want to understand how traditional RESTful APIs work if you haven't already - it'll help you appreciate the difference.

What If We Could Ask for Exactly What We Need?

Let's pause for a moment and think about this differently.

When you go to a restaurant, you don't just say "give me food." You look at the menu and say "I'd like the salmon, with rice, and hold the vegetables." You're describing exactly what you want.

But with APIs, we've been stuck with the equivalent of fixed combo meals. You can order "the user combo" or "the posts combo," but you can't customize what's in them.

What if APIs worked more like a conversation where you could describe exactly what you need?

Here's how that same user profile request might look:

query GetUserProfile($userId: ID!) {
  user(id: $userId) {
    name
    avatar
    posts(limit: 5) {
      title
      createdAt
      comments(limit: 3) {
        content
        author {
          name
        }
      }
    }
  }
}

Do you notice something interesting about this? The structure of the request matches exactly what you want back. You're literally describing the shape of the data you need.

This is GraphQL. It's a query language that lets you ask for exactly what you need, when you need it, all in a single request.

But how does this actually work? Let's explore that together.

How Does the Magic Happen?

Great question! Let's think about this step by step.

You know how traditional REST APIs work, right? You have different URLs for different resources - /users, /posts, /comments. It's like having separate departments in a store. If you want something from electronics, you go to the electronics department. If you want something from clothing, you go to the clothing department.

But what if there was a single information desk where you could ask for anything you needed from any department, and they'd bring it all to you at once?

That's essentially what GraphQL does. Instead of multiple endpoints, you have one endpoint (usually /graphql) that can handle any request.

When you send a GraphQL query, here's what happens:

First, your query arrives at the server as a string. The server looks at it and asks: "Is this a valid request?"

It checks your query against something called a schema. Think of the schema as a catalog of everything that's available. Just like you can't order something that's not on the menu, you can't ask for data that's not in the schema.

If your query is valid, the server moves to the next step: execution. This is where it gets interesting.

The server breaks down your query into little pieces and calls functions called resolvers for each piece of data you requested. The resolver for user.name might query the database, while the resolver for user.posts might call another service entirely.

Here's the beautiful part: all of these resolvers can run in parallel. While one resolver is getting the user's name, another can be fetching their posts, and another can be counting their followers.

Finally, the server takes all the results and assembles them into exactly the structure you requested. No extra fields, no missing pieces - just what you asked for.

Can you see why this is powerful? You're not limited to predefined responses. You can ask for exactly what your specific use case needs.

Let's Build Our First Query Together

Now that you understand the basic concept, let's walk through creating a GraphQL query step by step. Don't worry if you've never written one before - we'll figure it out together.

What Data Can We Ask For?

Before we can ask for data, we need to know what's available. This is where the schema comes in.

Think of the schema as a map of all the data you can access. It defines the types of data available and how they're related to each other. Here's a simple example:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
}

type Comment {
  id: ID!
  content: String!
  author: User!
}

What do you notice about this structure? Each type defines what fields are available. The exclamation marks (!) mean "this field is required and will never be null." Square brackets ([]) mean "this is a list of items."

Notice how the types are connected? A User has posts, each Post has an author (which is a User), and each Post has comments. These relationships let you traverse the data graph in your queries.

Your First Query

Let's say you're building an e-commerce site and you want to show product details. Looking at the schema, how would you ask for a product's name, price, and recent reviews?

Take a moment to think about it. Remember, you're describing the shape of the data you want...

Here's how you might approach it:

query GetProductDetails($productId: ID!) {
  product(id: $productId) {
    name
    price
    description
    reviews(limit: 5) {
      rating
      comment
      reviewer {
        name
      }
    }
  }
}

Does this make sense? You're saying "Get me the product with this ID, and give me its name, price, description, and the first 5 reviews, including each reviewer's name."

Notice how the query reads almost like English? That's one of GraphQL's strengths - queries are self-documenting.

What About Changing Data?

Reading data is great, but what happens when you need to create or update something?

In GraphQL, we use mutations for this. They work similarly to queries, but they're designed to modify data rather than just read it.

mutation CreatePost($input: PostInput!) {
  createPost(input: $input) {
    id
    title
    content
    author {
      name
    }
  }
}

Here's something cool: notice how you can specify exactly what data you want back after the mutation? You don't need a separate API call to get the updated information.

Let's Compare: How Would This Work with REST?

To really understand GraphQL's value, let's work through a real example. Imagine you're building a social media dashboard that needs to show user info, their recent posts, and follower count.

The REST Approach

With REST APIs, how do you think you'd get this data?

You'd probably need to make several requests:

// First, get the user
const userResponse = await fetch("/api/users/123");
const user = await userResponse.json();

// Then get their posts
const postsResponse = await fetch("/api/users/123/posts?limit=5");
const posts = await postsResponse.json();

// Finally, get follower count
const followersResponse = await fetch("/api/users/123/followers/count");
const followerCount = await followersResponse.json();

But remember what we learned about over-fetching? That user endpoint gives you everything:

{
  "id": 123,
  "name": "Alex Rodriguez",
  "email": "[email protected]",
  "avatar": "avatar.jpg",
  "phone": "+1234567890",
  "address": "456 Oak St",
  "birthdate": "1985-03-20",
  "preferences": { "theme": "dark" },
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

Your dashboard only needs the name and avatar. Can you imagine how this affects mobile users on slow connections? They're downloading and processing all that extra data for no reason.

The GraphQL Approach

Now, what if you could describe exactly what your dashboard needs in one request?

How would you structure that query? Think about it for a moment...

query Dashboard($userId: ID!) {
  user(id: $userId) {
    name
    avatar
    posts(limit: 5) {
      title
      createdAt
      likesCount
    }
    followersCount
  }
}

The response would be clean and focused:

{
  "data": {
    "user": {
      "name": "Alex Rodriguez",
      "avatar": "avatar.jpg",
      "posts": [
        {
          "title": "My thoughts on GraphQL",
          "createdAt": "2023-01-01T10:00:00Z",
          "likesCount": 42
        }
      ],
      "followersCount": 1337
    }
  }
}

What's the difference? One request instead of three. 60% less data transferred. No coordination needed between multiple API calls. Your dashboard loads faster, your users are happier, and your servers do less work.

But When Should You Actually Use GraphQL?

This is probably the most important question we'll explore together. GraphQL isn't a silver bullet - it's a tool that solves specific problems.

Let's think through some scenarios. Have you ever built a mobile app where every kilobyte of data matters?

Mobile networks can be unpredictable. Sometimes you're on 5G, sometimes you're on spotty 3G. Users abandon apps that take too long to load. In this environment, GraphQL's ability to minimize data transfer and reduce round trips becomes incredibly valuable.

What about when you're dealing with complex, interconnected data? Think of an e-commerce platform where products have variants, categories, reviews, and related items all connected together. With REST, you'd need to make separate API calls for each relationship. With GraphQL, you can traverse these relationships naturally in a single query.

Here's another scenario: Are you building multiple client applications? Maybe you have a web app, a mobile app, and an admin dashboard. Each needs different data from the same underlying resources.

With REST, you often end up creating custom endpoints for each client. The mobile app gets /api/mobile/user-profile, the web app gets /api/web/user-profile, and the admin gets /api/admin/user-profile. That's a lot of maintenance.

GraphQL lets each client request exactly what it needs. The mobile app can ask for just the essential fields, the web app can request more detailed information, and the admin can get everything including sensitive data.

But here's the thing - GraphQL isn't always the right choice. Can you think of scenarios where REST might be simpler?

If you're building a simple todo app with basic create, read, update, and delete operations, REST's straightforward approach might serve you better. The overhead of GraphQL could be overkill for such simple use cases.

Are file uploads a big part of your application? While GraphQL can handle uploads, REST's multipart form data approach is more straightforward and has better tooling support.

What about caching? If caching is critical to your application's performance, REST has some advantages. Each REST endpoint can be cached independently, while GraphQL queries are more dynamic and harder to cache effectively.

What Are the Real Trade-offs?

Let's be honest about GraphQL's challenges. Every technology has trade-offs, and understanding them helps you make better decisions.

First, there's the learning curve. GraphQL requires more upfront investment than REST. Your team needs to understand new concepts like schemas, resolvers, and query optimization. The tooling is also more complex - you'll need schema design tools, query analyzers, and specialized debugging capabilities.

But here's a more subtle challenge: Have you ever heard of the N+1 problem?

It's a common performance issue that can be especially tricky with GraphQL. Consider this innocent-looking query:

query GetUsers {
  users {
    name
    posts {
      title
      comments {
        content
        author {
          name
        }
      }
    }
  }
}

What do you think happens when this query executes? For each user, the server queries their posts. For each post, it queries the comments. For each comment, it queries the author. If you have 100 users with 10 posts each, and each post has 5 comments, you're looking at thousands of database queries.

This is where careful resolver design becomes crucial. You need tools like DataLoader that can batch similar requests together:

const userLoader = new DataLoader(async (userIds) => {
  return await User.findByIds(userIds);
});

const resolvers = {
  Comment: {
    author: (comment) => userLoader.load(comment.authorId),
  },
};

This batches all the author lookups into a single database query, dramatically improving performance.

Security is another consideration. GraphQL's flexibility is a double-edged sword. Clients can request any data they want, potentially exposing sensitive information or overwhelming your servers with expensive queries.

You'll need to implement query depth limiting, rate limiting, and field-level authorization. It's more complex than REST's simple endpoint-based security model.

What Problems Are You Trying to Solve?

As we wrap up our exploration, let's come back to the fundamental question: What problems are you trying to solve with your APIs?

GraphQL solves real problems that many developers face daily. If you're tired of making multiple API calls, dealing with over-fetching, or maintaining different endpoints for different clients, GraphQL might be exactly what you need.

But remember - GraphQL isn't perfect. It adds complexity and requires careful implementation. The key is understanding when that complexity is justified.

Are you building applications with complex data requirements? Do you have multiple clients that need different data subsets? Are you dealing with performance-sensitive mobile apps? These are the scenarios where GraphQL's benefits often outweigh its costs.

The technology represents a fundamental shift in how we think about APIs. Instead of thinking about resources and endpoints, we think about data and relationships. Instead of accepting whatever data structure the server provides, we describe exactly what we need.

If you want to give GraphQL a try, start small. Try GraphQL for a single feature or API endpoint. Get comfortable with the concepts and tooling. Then gradually expand your usage as your team gains experience.

Remember, the best technology is the one that solves your specific problems. What problems are you trying to solve with your APIs? That's where your GraphQL journey should begin.

If you found this exploration of GraphQL helpful, you might also want to read about RESTful APIs to understand the traditional approach that GraphQL builds upon and sometimes replaces.

Support ExplainThis

If you found this content helpful, please consider supporting our work with a one-time donation of whatever amount feels right to you through this Buy Me a Coffee page, or share the article with your friends to help us reach more readers.

Creating in-depth technical content takes significant time. Your support helps us continue producing high-quality educational content accessible to everyone.