GraphQL Fundamentals

What is GraphQL?

GraphQL is a query language for APIs that lets clients request exactly the data they need. Unlike REST where you get fixed responses, GraphQL gives you the power to shape your queries.

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)
• ❌ Under-fetching (need multiple requests)
• ❌ Multiple round trips

GraphQL: Single Endpoint, Flexible Queries

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

Benefits:

• ✅ Fetch exactly what you need
• ✅ Get related data in one request
• ✅ Single round trip

---

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": "john@example.com"
    }
  }
}

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: "jane@example.com") {
    id
    name
    email
  }
}

Response:

{
  "data": {
    "createUser": {
      "id": "456",
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

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: "alice@example.com") {
    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! 😱

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

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());
}

---

Resolvers: The Implementation

Resolvers are functions that fetch data for each field.

Resolver Structure

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());
    }
}

---

When to Use GraphQL vs REST

Use GraphQL When:

• ✅ Multiple clients with different data needs
• ✅ Mobile apps where bandwidth matters
• ✅ Complex relationships between data
• ✅ Rapidly evolving API requirements
• ✅ Real-time updates needed (subscriptions)

Use REST When:

• ✅ Simple CRUD operations
• ✅ Caching is critical (HTTP caching)
• ✅ File uploads (GraphQL handles this poorly)
• ✅ Simple APIs where over-fetching isn’t a problem
• ✅ Existing REST infrastructure

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
  }
}

✅ 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

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);
    }
}

---

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