GraphQL Fundamentals

What is GraphQL?

GraphQL is a query language and runtime for APIs developed by Facebook (now Meta) in 2012 and open-sourced in 2015. Unlike REST APIs that return fixed data structures, GraphQL allows clients to specify exactly what data they need, reducing over-fetching and under-fetching.

The Core Problem GraphQL Solves

Traditional REST APIs have a fundamental limitation: they return fixed data structures. If you need user data, you call /users/123 and get all user fields—even if you only need the name. If you need related data (like a user’s orders), you make multiple requests. This leads to:

• Over-fetching: Getting data you don’t need (wasting bandwidth)
• Under-fetching: Not getting enough data (requiring multiple requests)
• Multiple round trips: Slower performance due to network latency

GraphQL solves this by providing a single endpoint where clients can request exactly the data they need, including related data, in a single request.

Simple Analogy

Think of REST like a restaurant menu with fixed meals. You order “Meal #1” and get everything on that plate, even if you only wanted the salad.

GraphQL is like a buffet where you point to exactly what you want: “I’ll have the chicken, rice, and broccoli” - nothing more, nothing less.

Key Concepts

1. Single Endpoint - One URL for all operations
2. Client-Specified Queries - Client decides what data to fetch
3. Strongly Typed Schema - Schema defines all possible queries
4. Introspection - Schema is self-documenting
5. Real-time Subscriptions - WebSocket support for live updates

---

GraphQL vs REST: The Core Difference

REST: Multiple Endpoints, Fixed Responses

GET /users/123          → Returns full user object
GET /users/123/orders   → Returns all orders
GET /users/123/profile  → Returns full profile

Problems:

• Over-fetching (get data you don’t need) - Mobile app might only need name, but gets full user object with 20+ fields
• Under-fetching (need multiple requests) - Need user and orders? That’s 2+ requests
• Multiple round trips - Each request adds network latency, slowing down the app

GraphQL: Single Endpoint, Flexible Queries

query {
  user(id: 123) {
    name
    email
    orders {
      id
      total
    }
  }
}

Benefits:

• Fetch exactly what you need - Request only the fields you need, nothing more
• Get related data in one request - Fetch user and their orders in a single query
• Single round trip - One network request instead of multiple, reducing latency

---

GraphQL Schema: The Foundation

Schema defines what data is available and how to query it.

Basic Schema Example

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  items: [OrderItem!]!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String): User!
}

Type System

Type	Meaning	Example
String	Text	"John Doe"
Int	Integer	42
Float	Decimal	99.99
Boolean	True/False	true
ID	Unique identifier	"123"
!	Required (non-null)	String!
[Type]	Array	[String!]!

---

Queries: Fetching Data

Queries are for reading data. They’re like GET requests in REST.

Simple Query

query {
  user(id: "123") {
    name
    email
  }
}

Response:

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}

Query with Arguments

query {
  users(limit: 10, offset: 0) {
    id
    name
  }
}

Query with Nested Data

query {
  user(id: "123") {
    name
    email
    orders {
      id
      total
      items {
        product {
          name
          price
        }
        quantity
      }
    }
  }
}

This single query replaces multiple REST calls:

• GET /users/123
• GET /users/123/orders
• GET /orders/456/items
• GET /products/789

Query with Aliases

Get multiple versions of same field:

query {
  user1: user(id: "123") {
    name
  }
  user2: user(id: "456") {
    name
  }
}

Query with Fragments

Reusable field sets:

fragment UserInfo on User {
  id
  name
  email
}

query {
  user(id: "123") {
    ...UserInfo
    orders {
      id
    }
  }
}

---

Mutations: Modifying Data

Mutations are for creating, updating, or deleting data. Like POST/PUT/DELETE in REST.

Create Mutation

mutation {
  createUser(name: "Jane Doe", email: "[email protected]") {
    id
    name
    email
  }
}

Response:

{
  "data": {
    "createUser": {
      "id": "456",
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  }
}

Update Mutation

mutation {
  updateUser(id: "123", name: "John Smith") {
    id
    name
    email
  }
}

Delete Mutation

mutation {
  deleteUser(id: "123") {
    id
  }
}

Multiple Mutations

Execute multiple mutations in one request:

mutation {
  createUser(name: "Alice", email: "[email protected]") {
    id
  }
  createOrder(userId: "123", items: [...]) {
    id
  }
}

Mutation Ordering

GraphQL executes mutations sequentially (in order), but queries can be executed in parallel. This ensures data consistency.

---

Subscriptions: Real-Time Updates

Subscriptions provide real-time data using WebSockets.

Subscription Example

subscription {
  userUpdated(userId: "123") {
    id
    name
    email
  }
}

How it works:

1. Client subscribes via WebSocket
2. Server sends updates when data changes
3. Client receives real-time updates

Use Cases

• Live chat messages
• Real-time notifications
• Stock price updates
• Collaborative editing
• Live dashboards

---

The N+1 Query Problem

The biggest performance issue in GraphQL.

The Problem

query {
  users {
    name
    orders {  # N+1 problem!
      id
      total
    }
  }
}

What happens:

1. Query 1: SELECT * FROM users (gets 100 users)
2. Query 2: SELECT * FROM orders WHERE user_id = 1
3. Query 3: SELECT * FROM orders WHERE user_id = 2
4. … (100 more queries!)

Total: 1 + 100 = 101 queries! This is the N+1 query problem—one query to get the list, then N queries (one per item) to get related data.

Solution: DataLoader (Batching)

DataLoader batches requests:

How DataLoader works:

1. Collects all requests in a batch
2. Waits for next event loop tick
3. Executes single batched query
4. Distributes results to individual requests

DataLoader Implementation

💡 Tip: Click dropdown to switch between languages

Python

Python

"dataloader_example.py

from dataloader import DataLoader
import asyncio

# Create DataLoader for orders
order_loader = DataLoader(
    batch_load_fn=lambda user_ids: load_orders_for_users(user_ids)
)

async def get_user_with_orders(user_id):
    user = await get_user(user_id)

    # This will be batched!
    orders = await order_loader.load(user_id)

    return {
        "user": user,
        "orders": orders
    }

async def load_orders_for_users(user_ids):
    # Single query for all users
    orders = await db.query(
        "SELECT * FROM orders WHERE user_id IN ?",
        user_ids
    )

    # Group by user_id
    orders_by_user = {}
    for order in orders:
        if order.user_id not in orders_by_user:
            orders_by_user[order.user_id] = []
        orders_by_user[order.user_id].append(order)

    # Return in same order as requested
    return [orders_by_user.get(uid, []) for uid in user_ids]

Java

"DataLoaderExample.java

import org.dataloader.DataLoader;
import org.dataloader.DataLoaderRegistry;

// Create DataLoader for orders
DataLoader<Integer, List<Order>> orderLoader = DataLoader
    .newDataLoader(userIds -> {
        // Batch load orders for all users
        return CompletableFuture.supplyAsync(() -> {
            List<Order> orders = orderRepository.findByUserIdIn(userIds);

            // Group by user_id
            Map<Integer, List<Order>> ordersByUser = orders.stream()
                .collect(Collectors.groupingBy(Order::getUserId));

            // Return in same order as requested
            return userIds.stream()
                .map(uid -> ordersByUser.getOrDefault(uid, Collections.emptyList()))
                .collect(Collectors.toList());
        });
    });

// Usage in resolver
public CompletableFuture<List<Order>> getOrders(User user) {
    // This will be batched!
    return orderLoader.load(user.getId());
}

TypeScript

"dataloader-example.ts

import DataLoader from 'dataloader';

// Create DataLoader for orders
const orderLoader = new DataLoader<number, Order[]>(
    async (userIds: readonly number[]) => {
        // Batch load orders for all users
        const orders = await orderRepository.findByUserIdIn([...userIds]);

        // Group by user_id
        const ordersByUser = new Map<number, Order[]>();
        orders.forEach(order => {
            if (!ordersByUser.has(order.userId)) {
                ordersByUser.set(order.userId, []);
            }
            ordersByUser.get(order.userId)!.push(order);
        });

        // Return in same order as requested
        return userIds.map(userId => ordersByUser.get(userId) || []);
    }
);

// Usage in resolver
async function getUserWithOrders(userId: number) {
    const user = await getUser(userId);

    // This will be batched!
    const orders = await orderLoader.load(userId);

    return {
        user,
        orders
    };
}

C++

"dataloader_example.cpp

#include <vector>
#include <unordered_map>
#include <future>

class OrderDataLoader {
    // DataLoader for batching order requests
private:
    OrderRepository& orderRepository;
    std::unordered_map<int, std::shared_future<std::vector<Order>>> pending;

public:
    OrderDataLoader(OrderRepository& orderRepository)
        : orderRepository(orderRepository) {}

    std::vector<Order> load(int userId) {
        // This will be batched
        auto it = pending.find(userId);
        if (it == pending.end()) {
            // Create future for this user
            auto future = std::async(std::launch::async, [this, userId]() {
                return orderRepository.findByUserId(userId);
            });
            pending[userId] = future.share();
            return future.get();
        }
        return it->second.get();
    }

    void batchLoad(const std::vector<int>& userIds) {
        // Batch load all orders at once
        auto orders = orderRepository.findByUserIdIn(userIds);

        // Group by user_id
        std::unordered_map<int, std::vector<Order>> ordersByUser;
        for (const auto& order : orders) {
            ordersByUser[order.getUserId()].push_back(order);
        }

        // Store results
        for (int userId : userIds) {
            auto future = std::async(std::launch::deferred, [ordersByUser, userId]() {
                return ordersByUser[userId];
            });
            pending[userId] = future.share();
        }
    }
};

C#

"DataLoaderExample.cs

using DataLoader;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

public class OrderDataLoader {
    // DataLoader for batching order requests
    private readonly DataLoader<int, List<Order>> orderLoader;

    public OrderDataLoader(OrderRepository orderRepository) {
        this.orderLoader = new DataLoader<int, List<Order>>(
            async userIds => {
                // Batch load orders for all users
                var orders = await orderRepository.FindByUserIdInAsync(userIds.ToList());

                // Group by user_id
                var ordersByUser = orders
                    .GroupBy(o => o.UserId)
                    .ToDictionary(g => g.Key, g => g.ToList());

                // Return in same order as requested
                return userIds.Select(userId =>
                    ordersByUser.GetValueOrDefault(userId, new List<Order>())
                ).ToList();
            }
        );
    }

    public async Task<List<Order>> LoadAsync(int userId) {
        // This will be batched!
        return await orderLoader.LoadAsync(userId);
    }
}

// Usage in resolver
public async Task<UserWithOrders> GetUserWithOrdersAsync(int userId) {
    var user = await userRepository.FindByIdAsync(userId);

    // This will be batched!
    var orders = await orderDataLoader.LoadAsync(userId);

    return new UserWithOrders {
        User = user,
        Orders = orders
    };
}

---

Resolvers: The Implementation

Resolvers are functions that fetch data for each field.

Resolver Structure

💡 Tip: Click dropdown to switch between languages

Python

Python

"resolvers.py

from ariadne import QueryType, MutationType
from typing import Optional, List

query = QueryType()
mutation = MutationType()

@query.field("user")
def resolve_user(_, info, id: str) -> Optional[dict]:
    """Resolver for user query"""
    return user_repository.find_by_id(id)

@query.field("users")
def resolve_users(_, info) -> List[dict]:
    """Resolver for users query"""
    return user_repository.find_all()

@mutation.field("createUser")
def resolve_create_user(_, info, name: str, email: str) -> dict:
    """Resolver for createUser mutation"""
    user = user_repository.create(name=name, email=email)
    return user

# Field resolvers (for nested fields)
def resolve_user_orders(user: dict, info) -> List[dict]:
    """Resolver for User.orders field"""
    return order_repository.find_by_user_id(user["id"])

Java

"Resolvers.java

import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import com.coxautodev.graphql.tools.GraphQLMutationResolver;

@Component
public class UserResolver implements GraphQLQueryResolver, GraphQLMutationResolver {
    private final UserRepository userRepository;

    public User user(String id) {
        // Resolver for user query
        return userRepository.findById(id).orElse(null);
    }

    public List<User> users() {
        // Resolver for users query
        return userRepository.findAll();
    }

    public User createUser(String name, String email) {
        // Resolver for createUser mutation
        User user = new User(name, email);
        return userRepository.save(user);
    }
}

// Field resolver for nested fields
@Component
public class UserFieldResolver implements GraphQLResolver<User> {
    private final OrderRepository orderRepository;

    public List<Order> orders(User user) {
        // Resolver for User.orders field
        return orderRepository.findByUserId(user.getId());
    }
}

TypeScript

"resolvers.ts

import { GraphQLResolveInfo } from 'graphql';

const resolvers = {
    Query: {
        user: async (_: any, { id }: { id: string }) => {
            // Resolver for user query
            return await userRepository.findById(id);
        },
        users: async () => {
            // Resolver for users query
            return await userRepository.findAll();
        }
    },
    Mutation: {
        createUser: async (_: any, { name, email }: { name: string, email: string }) => {
            // Resolver for createUser mutation
            return await userRepository.create({ name, email });
        }
    },
    User: {
        orders: async (user: User) => {
            // Field resolver for User.orders field
            return await orderRepository.findByUserId(user.id);
        }
    }
};

export default resolvers;

C++

"resolvers.cpp

#include <string>
#include <vector>
#include <optional>

class GraphQLResolvers {
private:
    UserRepository& userRepository;
    OrderRepository& orderRepository;

public:
    GraphQLResolvers(UserRepository& userRepo, OrderRepository& orderRepo)
        : userRepository(userRepo), orderRepository(orderRepo) {}

    std::optional<User> resolveUser(const std::string& id) {
        // Resolver for user query
        return userRepository.findById(id);
    }

    std::vector<User> resolveUsers() {
        // Resolver for users query
        return userRepository.findAll();
    }

    User resolveCreateUser(const std::string& name, const std::string& email) {
        // Resolver for createUser mutation
        return userRepository.create(name, email);
    }

    std::vector<Order> resolveUserOrders(const User& user) {
        // Field resolver for User.orders field
        return orderRepository.findByUserId(user.getId());
    }
};

C#

"Resolvers.cs

using GraphQL.Types;

public class UserQuery : ObjectGraphType {
    public UserQuery(UserRepository userRepository) {
        Field<UserType>(
            "user",
            arguments: new QueryArguments(
                new QueryArgument<NonNullGraphType<IdGraphType>> { Name = "id" }
            ),
            resolve: context => {
                // Resolver for user query
                string id = context.GetArgument<string>("id");
                return userRepository.FindById(id);
            }
        );

        Field<ListGraphType<UserType>>(
            "users",
            resolve: context => {
                // Resolver for users query
                return userRepository.FindAll();
            }
        );
    }
}

public class UserMutation : ObjectGraphType {
    public UserMutation(UserRepository userRepository) {
        Field<UserType>(
            "createUser",
            arguments: new QueryArguments(
                new QueryArgument<NonNullGraphType<StringGraphType>> { Name = "name" },
                new QueryArgument<NonNullGraphType<StringGraphType>> { Name = "email" }
            ),
            resolve: context => {
                // Resolver for createUser mutation
                string name = context.GetArgument<string>("name");
                string email = context.GetArgument<string>("email");
                return userRepository.Create(name, email);
            }
        );
    }
}

public class UserType : ObjectGraphType<User> {
    public UserType(OrderRepository orderRepository) {
        Field(x => x.Id);
        Field(x => x.Name);
        Field(x => x.Email);
        Field<ListGraphType<OrderType>>(
            "orders",
            resolve: context => {
                // Field resolver for User.orders field
                return orderRepository.FindByUserId(context.Source.Id);
            }
        );
    }
}

---

When to Use GraphQL vs REST

Use GraphQL When:

• Multiple clients with different data needs - Web app needs all fields, mobile app needs minimal fields
• Mobile apps where bandwidth matters - Reducing data transfer saves battery and improves performance
• Complex relationships between data - Easier to fetch related data in one query
• Rapidly evolving API requirements - Schema changes don’t break existing queries (backward compatible)
• Real-time updates needed (subscriptions) - Built-in WebSocket support for live data

Use REST When:

• Simple CRUD operations - REST is simpler for basic create/read/update/delete
• Caching is critical (HTTP caching) - REST benefits from HTTP caching infrastructure
• File uploads (GraphQL handles this poorly) - REST is better suited for file operations
• Simple APIs where over-fetching isn’t a problem - If bandwidth isn’t a concern, REST is simpler
• Existing REST infrastructure - If you already have REST APIs, migration might not be worth it

Hybrid Approach

Many companies use both! REST for simple operations, GraphQL for complex queries. You don’t have to choose one or the other.

---

GraphQL Best Practices

1. Use Pagination

Bad:

query {
  users {  # Could return millions!
    id
    name
  }
}

Why it’s bad: Without pagination, a query could return millions of records, causing performance issues, memory problems, and timeouts.

Good:

query {
  users(first: 10, after: "cursor123") {
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

2. Limit Query Depth

Prevent deeply nested queries:

MAX_QUERY_DEPTH = 10

def validate_query_depth(query, max_depth=MAX_QUERY_DEPTH):
    depth = calculate_depth(query)
    if depth > max_depth:
        raise GraphQLError("Query too deep")

3. Use Field-Level Authorization

Authorize at field level:

@query.field("user")
def resolve_user(_, info, id: str):
    user = user_repository.find_by_id(id)

    # Check if user can access email field
    if not can_access_field(info, "email"):
        user.pop("email")  # Remove email from response

    return user

4. Implement Query Complexity Analysis

Prevent expensive queries:

def calculate_complexity(query):
    complexity = 0
    for field in query.fields:
        complexity += field.complexity
        if field.has_list:
            complexity *= field.list_size
    return complexity

if calculate_complexity(query) > MAX_COMPLEXITY:
    raise GraphQLError("Query too complex")

5. Use Introspection Wisely

Disable introspection in production (or limit it):

# Disable introspection
schema = make_executable_schema(type_defs, resolvers)
schema.introspection = False  # In production

---

LLD Connection: Implementing GraphQL

At the code level, GraphQL translates to resolvers, schema definitions, and DataLoader patterns.

Complete Example

💡 Tip: Click dropdown to switch between languages

Python

Python

"graphql_service.py

from ariadne import make_executable_schema, QueryType, MutationType
from dataloader import DataLoader

# Schema definition
type_defs = """
type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  items: [OrderItem!]!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
}
"""

query = QueryType()
mutation = MutationType()

# DataLoaders
order_loader = DataLoader(
    batch_load_fn=lambda user_ids: load_orders_batch(user_ids)
)

@query.field("user")
def resolve_user(_, info, id: str):
    return user_repository.find_by_id(id)

@query.field("users")
def resolve_users(_, info):
    return user_repository.find_all()

@mutation.field("createUser")
def resolve_create_user(_, info, name: str, email: str):
    return user_repository.create(name=name, email=email)

# Field resolver with DataLoader
def resolve_user_orders(user, info):
    return order_loader.load(user["id"])

schema = make_executable_schema(type_defs, [query, mutation])

Java

"GraphQLService.java

import graphql.GraphQL;
import graphql.schema.GraphQLSchema;
import com.coxautodev.graphql.tools.SchemaParser;

@Component
public class GraphQLService {
    private final GraphQL graphQL;

    public GraphQLService(UserResolver userResolver) {
        // Schema file: schema.graphqls
        GraphQLSchema schema = SchemaParser.newParser()
            .file("schema.graphqls")
            .resolvers(userResolver)
            .build()
            .makeExecutableSchema();

        this.graphQL = GraphQL.newGraphQL(schema)
            .queryExecutionStrategy(new BatchedExecutionStrategy())
            .build();
    }

    public ExecutionResult execute(String query) {
        return graphQL.execute(query);
    }
}

TypeScript

"graphql-service.ts

import { GraphQLSchema, GraphQLObjectType, GraphQLString, GraphQLList, GraphQLID, buildSchema } from 'graphql';
import { graphqlHTTP } from 'express-graphql';
import DataLoader from 'dataloader';

// Schema definition
const typeDefs = `
type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  items: [OrderItem!]!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
}
`;

// DataLoaders
const orderLoader = new DataLoader<number, Order[]>(
    async (userIds: readonly number[]) => {
        const orders = await orderRepository.findByUserIdIn([...userIds]);
        const ordersByUser = new Map<number, Order[]>();
        orders.forEach(order => {
            if (!ordersByUser.has(order.userId)) {
                ordersByUser.set(order.userId, []);
            }
            ordersByUser.get(order.userId)!.push(order);
        });
        return userIds.map(userId => ordersByUser.get(userId) || []);
    }
);

// Resolvers
const resolvers = {
    Query: {
        user: async (_: any, { id }: { id: string }) => {
            return await userRepository.findById(id);
        },
        users: async () => {
            return await userRepository.findAll();
        }
    },
    Mutation: {
        createUser: async (_: any, { name, email }: { name: string, email: string }) => {
            return await userRepository.create({ name, email });
        }
    },
    User: {
        orders: async (user: User) => {
            return await orderLoader.load(user.id);
        }
    }
};

const schema = buildSchema(typeDefs);

C++

"graphql_service.cpp

#include <string>
#include <vector>

class GraphQLService {
private:
    GraphQLSchema schema;
    UserRepository& userRepository;
    OrderRepository& orderRepository;
    OrderDataLoader orderLoader;

public:
    GraphQLService(UserRepository& userRepo, OrderRepository& orderRepo)
        : userRepository(userRepo), orderRepository(orderRepo), orderLoader(orderRepo) {
        // Build schema
        schema = buildSchema();
    }

    ExecutionResult execute(const std::string& query) {
        // Parse and execute GraphQL query
        auto parsedQuery = parseQuery(query);
        return executeQuery(parsedQuery);
    }

private:
    GraphQLSchema buildSchema() {
        // Schema definition (simplified)
        // In production, use a GraphQL library
        return GraphQLSchema();
    }

    ExecutionResult executeQuery(const ParsedQuery& query) {
        // Execute query using resolvers
        // Simplified implementation
        return ExecutionResult();
    }
};

C#

"GraphQLService.cs

using GraphQL;
using GraphQL.Types;

public class GraphQLService {
    // GraphQL service implementation
    private readonly GraphQLSchema schema;

    public GraphQLService(UserRepository userRepository, OrderRepository orderRepository) {
        // Build schema
        var schemaBuilder = new SchemaBuilder();

        schemaBuilder.Query = new UserQuery(userRepository);
        schemaBuilder.Mutation = new UserMutation(userRepository);

        // Register types
        schemaBuilder.Types.Add(new UserType(orderRepository));
        schemaBuilder.Types.Add(new OrderType());

        this.schema = schemaBuilder.Build();
    }

    public ExecutionResult Execute(string query) {
        // Execute GraphQL query
        var executor = new DocumentExecutor();
        var document = new GraphQLParser().Parse(query);

        return executor.ExecuteAsync(new ExecutionOptions {
            Schema = schema,
            Query = query,
            Document = document
        }).Result;
    }
}

---

Key Takeaways

Ask for What You Need

GraphQL lets clients specify exactly what data they need, reducing over-fetching and under-fetching.

Watch for N+1

The N+1 query problem is GraphQL’s biggest performance issue. Use DataLoader to batch requests.

Resolvers Fetch Data

Resolvers are functions that fetch data for each field. They’re where your business logic lives.

Schema is Contract

GraphQL schema defines your API contract. It’s self-documenting and strongly typed.

---

Next Steps

• Learn gRPC & Protocol Buffers - high-performance binary protocol
• Understand API Gateway Pattern - single entry point for APIs
• Master Rate Limiting - controlling API usage