Query-Based API Model - GraphQL: Query-Based API Architecture | OneNoughtOne

0/319

System Design (HLD)GraphQL

GraphQL: Query-Based API Architecture

LevelIntermediate

Duration90 mins

TopicGraphQL

1 / 5

Query-Based API Model

A New Paradigm for API Communication

In 2012, Facebook faced an engineering crisis. Their mobile apps were struggling with performance—not because the servers were slow, but because the REST APIs serving them were fundamentally misaligned with what mobile clients actually needed. The apps would make multiple round-trips to fetch related data, receive payloads bloated with unused fields, and waste precious mobile bandwidth on information that would never be displayed.

The solution wasn't to optimize REST—it was to rethink the entire API paradigm. What emerged was GraphQL: a query language for APIs that inverts the traditional relationship between client and server. Rather than servers defining rigid endpoints that return predetermined data, clients would express exactly what they need, and servers would fulfill those requests precisely.

This wasn't merely a technical improvement—it was a philosophical shift in how we think about API contracts.

What You Will Learn

By the end of this page, you will understand the fundamental shift GraphQL represents from resource-based APIs to query-based APIs. You'll grasp why this distinction matters for distributed systems, learn the core mechanics of how GraphQL queries work, and build intuition for when this paradigm provides genuine advantages over traditional approaches.

The Resource-Centric vs Query-Centric Divide

To appreciate GraphQL, we must first understand the paradigm it challenges. REST APIs are resource-centric: the server defines resources (users, posts, comments) and exposes endpoints for each. The client navigates these endpoints like a tourist following a predetermined path through a city.

In a resource-centric model:

The server dictates what data exists at each endpoint
Clients compose multiple calls to gather related data
Response shapes are determined by the server, not the client
Changes to data needs often require new endpoints or versioning

GraphQL inverts this entirely. It is query-centric: the client describes the shape of data it needs, and the server fulfills that specific request. The client becomes the architect of its own data requirements.

Paradigm Comparison: Resource-Centric vs Query-Centric
Aspect	REST (Resource-Centric)	GraphQL (Query-Centric)
Data Shape	Server-defined response structure	Client-defined response structure
Endpoints	Multiple specialized endpoints	Single endpoint, infinite queries
Data Fetching	Multiple round-trips for related data	Single request for nested data
Contract Evolution	Versioning or new endpoints	Schema evolution with deprecation
Coupling	Clients coupled to endpoint structure	Clients coupled to schema types
Documentation	External (OpenAPI/Swagger)	Intrinsic (self-documenting schema)

The philosophical distinction:

REST says: "Here are the resources I'm exposing. You can GET, POST, PUT, DELETE them. I'll tell you what you get back."

GraphQL says: "Here's all the data that exists and how it connects. Tell me exactly what you want, and I'll return precisely that—nothing more, nothing less."

This shift has profound implications:

Client Autonomy: Clients no longer depend on backend teams to create new endpoints for every UI change
Network Efficiency: No over-fetching (receiving unused data) or under-fetching (needing multiple calls)
Type Safety: The schema provides a compile-time contract that catches errors before runtime
Introspection: Clients can query the schema itself to understand what's available

Not a REST Replacement

GraphQL and REST solve different problems optimally. REST excels at caching, simple CRUD operations, and scenarios where server-defined resources map cleanly to client needs. GraphQL shines when clients have diverse, complex data requirements. The goal isn't to replace REST—it's to understand when each paradigm serves you better.

Anatomy of a GraphQL Query

A GraphQL query is a hierarchical data request that mirrors the shape of the expected response. This isomorphism—where the query structure matches the response structure—is one of GraphQL's most powerful properties.

The fundamental principle: What you ask for is what you get.

Let's examine a complete query to understand its components:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# Query for a user's profile with their recent posts and post comments
query GetUserProfile($userId: ID!, $postLimit: Int = 10) {
  # Root field: entry point into the graph
  user(id: $userId) {
    # Scalar fields: primitive values
    id
    name
    email
    avatarUrl
    createdAt
    
    # Object field: nested type with its own fields
    profile {
      bio
      location
      website
    }
    
    # Connection field: list of related objects with arguments
    posts(first: $postLimit, orderBy: CREATED_AT_DESC) {
      # Edges pattern for pagination
      edges {
        node {
          id
          title
          content
          publishedAt
          
          # Deeply nested: comments on posts
          comments(first: 5) {
            totalCount
            edges {
              node {
                id
                body
                author {
                  name
                  avatarUrl
                }
              }
            }
          }
        }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    
    # Additional fields can be requested in same query
    followersCount
    followingCount
  }
}

Let's dissect this query layer by layer:

1. Operation Type and Name

query GetUserProfile($userId: ID!, $postLimit: Int = 10)

query is the operation type (others are mutation and subscription)
GetUserProfile is the operation name (required for certain tooling, helpful for debugging)
$userId and $postLimit are variables that parameterize the query
ID! means the variable is a non-nullable ID type
= 10 provides a default value

2. Root Fields

user(id: $userId) { ... }

user is a root field—an entry point into the data graph
(id: $userId) provides arguments to narrow the query
The schema defines which fields can be queried at the root level

3. Scalar Fields

id
name
email

Scalars are leaf nodes—they resolve to concrete values
Built-in scalars: String, Int, Float, Boolean, ID
Custom scalars can represent dates, URLs, JSON, etc.

4. Object Fields

profile {
  bio
  location
}

Object fields resolve to another type with its own fields
You must specify which sub-fields you want—no automatic expansion

5. Connection Fields (Pagination)

posts(first: 10, orderBy: CREATED_AT_DESC) {
  edges { ... }
  pageInfo { ... }
}

The edges/node/pageInfo pattern is the Relay connection specification
Enables cursor-based pagination with consistent metadata

Query Response Isomorphism

The response to this query will have exactly the same shape as the query itself. If you request user.posts.edges.node.title, you'll receive { user: { posts: { edges: [{ node: { title: '...' } }] } } }. This predictability makes client-side data handling dramatically simpler—you always know what you'll receive.

The Execution Model

Understanding how GraphQL executes queries is crucial for designing efficient schemas and resolvers. The execution follows a predictable, depth-first traversal pattern.

The Execution Algorithm:

Parse: Convert the query string into an Abstract Syntax Tree (AST)
Validate: Check the AST against the schema for type correctness
Execute: Traverse the AST, invoking resolvers for each field
Serialize: Convert the result into JSON for transport

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
interface ExecutionContext {
  schema: GraphQLSchema;
  document: DocumentNode;      // Parsed AST
  variables: Record<string, any>;
  rootValue: any;              // Entry point for root resolvers
  context: any;                // Shared context (auth, dataloaders, etc.)
}
 
async function executeQuery(ctx: ExecutionContext): Promise<ExecutionResult> {
  // Step 1: Validate query against schema
  const errors = validate(ctx.schema, ctx.document);
  if (errors.length > 0) {
    return { errors };
  }
  
  // Step 2: Extract the operation from the document
  const operation = getOperation(ctx.document, ctx.operationName);
  
  // Step 3: Execute root fields in parallel (for queries) or serially (for mutations)
  const rootType = getRootType(ctx.schema, operation.operation);
  
  // Step 4: Recursively resolve each field
  const data = await executeSelectionSet(
    operation.selectionSet,
    rootType,
    ctx.rootValue,
    ctx
  );
  
  return { data };
}
 
async function executeSelectionSet(
  selectionSet: SelectionSetNode,
  parentType: GraphQLObjectType,
  sourceValue: any,
  ctx: ExecutionContext
): Promise<Record<string, any>> {
  const result: Record<string, any> = {};
  
  // Process each field in the selection set
  for (const field of selectionSet.selections) {
    const fieldName = field.name.value;
    const fieldDef = parentType.getFields()[fieldName];
    
    // Get the resolver for this field (or use default resolver)
    const resolver = fieldDef.resolve ?? defaultFieldResolver;
    
    // Call the resolver with (parent, args, context, info)
    const resolvedValue = await resolver(
      sourceValue,           // Parent object
      getArgumentValues(field, fieldDef, ctx.variables),
      ctx.context,           // Shared context
      buildResolveInfo(field, fieldDef, parentType, ctx)
    );
    
    // If the field has a sub-selection, recurse
    if (field.selectionSet && resolvedValue != null) {
      const fieldType = getNamedType(fieldDef.type);
      
      if (isListType(fieldDef.type)) {
        // Handle array fields
        result[fieldName] = await Promise.all(
          resolvedValue.map(item => 
            executeSelectionSet(field.selectionSet, fieldType, item, ctx)
          )
        );
      } else {
        // Handle object fields
        result[fieldName] = await executeSelectionSet(
          field.selectionSet, 
          fieldType, 
          resolvedValue, 
          ctx
        );
      }
    } else {
      result[fieldName] = resolvedValue;
    }
  }
  
  return result;
}

Key Execution Properties:

1. Depth-First Traversal The executor walks the query tree depth-first, meaning nested fields are resolved before moving to sibling fields. This enables the common pattern of passing parent data to child resolvers.

2. Resolver Independence Each field is resolved independently by its resolver function. The resolver for user.posts has no knowledge of whether user.email was also requested—it simply returns posts for the given user.

3. Parallelism at Each Level Fields at the same level can be resolved in parallel. If you request both user.posts and user.followers, both resolvers can execute concurrently.

4. The N+1 Problem The independence of resolvers creates a classic challenge. Consider:

query {
  posts(first: 10) {
    author {    # This resolver is called 10 times!
      name
    }
  }
}

Without optimization, this executes 1 query for posts + 10 queries for authors = 11 queries. The solution is DataLoader, which we'll explore in the resolvers section.

Query Complexity Matters

Because clients control query depth and breadth, malicious or naive queries can create exponential resolver calls. A query requesting 100 users, each with 100 posts, each with 100 comments, triggers 1,000,000 resolver invocations. Production GraphQL servers must implement query complexity analysis and depth limiting.

Mutations and Side Effects

While queries are read operations that can execute in parallel, mutations represent write operations that must execute serially to maintain consistency.

The Mutation Contract:

Mutations execute root fields in sequence, not parallel
Each mutation returns data (enabling "mutate and refresh" in a single request)
The mutation name should be a verb describing the action
Input types encapsulate mutation arguments

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# Mutation for creating a post with proper input typing
mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    # Return the created resource
    post {
      id
      title
      content
      publishedAt
      author {
        id
        name
      }
    }
    # Return operation metadata
    userErrors {
      field
      message
      code
    }
  }
}
 
# The input type encapsulates all mutation arguments
input CreatePostInput {
  title: String!
  content: String!
  categoryId: ID
  tags: [String!]
  publishImmediately: Boolean = false
}
 
# The payload type provides structured results
type CreatePostPayload {
  post: Post
  userErrors: [UserError!]!
}
 
type UserError {
  field: [String!]        # Path to the field that caused the error
  message: String!        # Human-readable error message
  code: ErrorCode!        # Machine-readable error code
}
 
# Example of compound mutations
mutation UpdateUserAndPosts(
  $userId: ID!
  $userInput: UpdateUserInput!
  $postUpdates: [UpdatePostInput!]!
) {
  # These execute in sequence, top to bottom
  updateUser(id: $userId, input: $userInput) {
    user { id name }
  }
  
  updatePosts(inputs: $postUpdates) {
    updatedCount
    posts { id title }
  }
  
  # Can refresh any data after mutations
  user(id: $userId) {
    postsCount
    lastUpdatedAt
  }
}

Mutation Design Best Practices:

1. Input Objects for Complex Mutations

# Instead of:
mutation { createPost(title: String!, content: String!, ...) }

# Prefer:
mutation { createPost(input: CreatePostInput!) }

Input objects group related arguments, enable backwards-compatible additions, and provide better documentation.

2. Payload Types with User Errors Rather than throwing exceptions for validation errors, return them in a structured userErrors array. This allows:

Partial success reporting
Field-level error attribution
Machine-readable error codes for client handling

3. Single Responsibility Each mutation should do one logical thing. createPost creates a post. Don't combine unrelated actions—let clients compose multiple mutations if needed.

4. Idempotency Considerations For critical mutations, consider idempotency keys:

mutation ChargePayment(
  $input: ChargePaymentInput!
  $idempotencyKey: String!
) {
  chargePayment(input: $input, idempotencyKey: $idempotencyKey) {
    payment { id status }
  }
}

Mutations Return Data

Unlike REST, where a POST might return 201 Created with minimal data, GraphQL mutations can return any data the client requests. This eliminates the need for a follow-up query—the client gets the created resource, related data, and any computed fields in a single round-trip.

Subscriptions and Real-Time Data

The third operation type in GraphQL is the subscription—a long-lived connection that streams data to clients as events occur. This completes GraphQL's coverage of the data flow spectrum:

Query: Client pulls data on demand
Mutation: Client pushes changes to server
Subscription: Server pushes changes to client

How Subscriptions Work:

Client sends a subscription document (looks like a query)
Server establishes a persistent connection (typically WebSocket)
When relevant events occur, server executes the subscription and pushes results
Connection remains open until explicitly closed or times out

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# Subscribe to new messages in a chat room
subscription OnMessageAdded($roomId: ID!) {
  messageAdded(roomId: $roomId) {
    id
    content
    createdAt
    author {
      id
      name
      avatarUrl
    }
  }
}
 
# Subscribe to post updates with filtering
subscription OnPostUpdated($authorId: ID, $category: Category) {
  postUpdated(filter: { authorId: $authorId, category: $category }) {
    # Event type helps clients handle different scenarios
    event
    post {
      id
      title
      content
      updatedAt
    }
    previousValues {
      title
      content
    }
  }
}
 
# Server-side subscription resolver (conceptual)
const resolvers = {
  Subscription: {
    messageAdded: {
      // Subscribe function returns an AsyncIterator
      subscribe: (_, { roomId }, { pubsub }) => {
        return pubsub.asyncIterator(`ROOM_${roomId}`);
      },
      // Optional: transform the published payload
      resolve: (payload) => payload.message
    }
  }
};
 
# Publishing events (typically from mutations)
async function sendMessage(roomId: string, content: string, authorId: string) {
  const message = await db.messages.create({ roomId, content, authorId });
  
  // Publish to subscribers
  pubsub.publish(`ROOM_${roomId}`, { message });
  
  return message;
}

Subscription Architecture Considerations:

1. Transport Layer Subscriptions typically use WebSocket for bidirectional communication. Alternatives include:

Server-Sent Events (SSE) for one-way streaming
HTTP/2 Server Push
Polling (fallback, not recommended)

2. Scalability Challenges Each subscription holds a persistent connection. At scale:

Connection state must be distributed across servers
Pub/sub systems (Redis, Kafka) propagate events to the right servers
Connection limits become a real constraint

3. Filtering and Authorization Every pushed event should be filtered and authorized:

const resolvers = {
  Subscription: {
    messageAdded: {
      subscribe: withFilter(
        (_, { roomId }) => pubsub.asyncIterator(`ROOM_${roomId}`),
        (payload, variables, context) => {
          // Only send to users who can see this room
          return canAccessRoom(context.user, payload.roomId);
        }
      )
    }
  }
};

4. Ordering and Delivery Guarantees Unlike queries that execute once, subscriptions deliver multiple events over time. Consider:

At-least-once delivery (with client-side deduplication)
Event ordering guarantees within a subscription
Reconnection handling and missed event recovery

Subscription Sweet Spots

Subscriptions excel for: chat applications, live dashboards, collaborative editing, live sports scores, stock tickers, and notification systems. They're overkill for: data that changes rarely, scenarios where polling is acceptable, or when clients can't maintain persistent connections.

Fragments and Query Composition

As applications grow, queries become repetitive. You might request user fields in dozens of places. Fragments solve this by extracting reusable field selections.

Why Fragments Matter:

DRY Principle: Define field selections once, use everywhere
Component Colocation: React components can define their own data requirements
Type Safety: TypeScript can generate types from fragments
Polymorphic Queries: Handle union types and interfaces cleanly

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# Define a reusable fragment
fragment UserBasicInfo on User {
  id
  name
  avatarUrl
  email
}
 
fragment PostPreview on Post {
  id
  title
  excerpt
  publishedAt
  author {
    ...UserBasicInfo
  }
}
 
fragment PostDetails on Post {
  ...PostPreview
  content
  category
  tags
  comments(first: 10) {
    edges {
      node {
        id
        body
        author {
          ...UserBasicInfo
        }
      }
    }
  }
}
 
# Using fragments in queries
query GetUserFeed($userId: ID!) {
  user(id: $userId) {
    ...UserBasicInfo
    
    feed(first: 20) {
      edges {
        node {
          ...PostPreview
        }
      }
    }
    
    savedPosts(first: 10) {
      edges {
        node {
          ...PostPreview
        }
      }
    }
  }
}
 
query GetSinglePost($postId: ID!) {
  post(id: $postId) {
    ...PostDetails
  }
}
 
# Inline fragments for polymorphic types (union/interface)
query GetFeedItems($userId: ID!) {
  user(id: $userId) {
    feed(first: 20) {
      edges {
        node {
          # Common fields
          id
          createdAt
          
          # Type-specific fields via inline fragments
          ... on Post {
            title
            content
          }
          
          ... on Article {
            headline
            synopsis
            publication {
              name
            }
          }
          
          ... on Photo {
            imageUrl
            caption
            dimensions {
              width
              height
            }
          }
        }
      }
    }
  }
}

Fragment-Driven Development:

In modern GraphQL applications, fragments enable a powerful pattern called component colocation. Each UI component defines the fragment for precisely the data it needs:

// UserAvatar.tsx
export const UserAvatar_user = gql`
  fragment UserAvatar_user on User {
    avatarUrl
    name
  }
`;

// PostCard.tsx  
export const PostCard_post = gql`
  fragment PostCard_post on Post {
    id
    title
    excerpt
    author {
      ...UserAvatar_user
    }
  }
  ${UserAvatar_user}
`;

This pattern ensures:

Components declare exactly what they need—no more, no less
Adding a field to a component automatically updates all queries using that fragment
TypeScript types can be generated per-fragment for perfect type safety
The query becomes a composition of component requirements

Fragments Are Compile-Time Only

Fragments are expanded at query parse time—the server never sees fragment references. They're purely a client-side DRY mechanism. The final query sent to the server is a fully expanded document with all fragments inlined.

Introspection and Self-Documentation

One of GraphQL's most distinctive features is introspection—the ability to query the schema itself. This isn't just a debugging convenience; it enables an entire ecosystem of tooling.

What Introspection Provides:

Complete type information for every type in the schema
Field signatures including arguments and return types
Deprecation metadata for graceful evolution
Documentation embedded directly in the schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# Get all types in the schema
{
  __schema {
    types {
      name
      kind       # OBJECT, INTERFACE, UNION, ENUM, INPUT_OBJECT, SCALAR
      description
    }
  }
}
 
# Get details about a specific type
{
  __type(name: "User") {
    name
    description
    fields {
      name
      description
      type {
        name
        kind
        ofType {    # For NON_NULL and LIST wrappers
          name
          kind
        }
      }
      args {
        name
        description
        type {
          name
        }
        defaultValue
      }
      isDeprecated
      deprecationReason
    }
  }
}
 
# Full introspection query (used by GraphiQL, Playground, etc.)
query IntrospectionQuery {
  __schema {
    queryType { name }
    mutationType { name }
    subscriptionType { name }
    types {
      ...FullType
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue
      }
    }
  }
}
 
fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args { ...InputValue }
    type { ...TypeRef }
    isDeprecated
    deprecationReason
  }
  inputFields { ...InputValue }
  interfaces { ...TypeRef }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes { ...TypeRef }
}
 
fragment InputValue on __InputValue {
  name
  description
  type { ...TypeRef }
  defaultValue
}
 
fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        # ... can be deeper for complex type wrappers
      }
    }
  }
}

Introspection-Powered Tooling:

1. GraphQL IDEs (GraphiQL, Apollo Studio, Insomnia)

Auto-complete field names as you type
Show inline documentation from schema descriptions
Validate queries before sending
Explore the schema interactively

2. Code Generation

Generate TypeScript types from the schema
Generate client-side query hooks (Apollo, urql)
Generate mock data for testing
Generate documentation sites

3. Static Analysis

Validate queries at build time against the schema
Detect breaking changes between schema versions
Enforce query complexity limits

4. Schema Registries

Track schema evolution over time
Validate changes against existing client queries
Generate changelogs automatically

Disable Introspection in Production

While introspection is invaluable during development, it exposes your entire API surface. In production, disable introspection to prevent attackers from mapping your API. Use API keys and separate development environments for legitimate schema exploration.

Summary: The Query-Based Foundation

We've established the conceptual foundation for understanding GraphQL as a query-based API paradigm. Let's consolidate the key insights:

Key Takeaways

•Query-Centric vs Resource-Centric: GraphQL inverts the traditional API model—clients describe desired data, servers fulfill exactly that request.
•Query Isomorphism: The structure of a query mirrors the structure of its response, providing predictable, self-documenting data contracts.
•Three Operation Types: Queries (read), Mutations (write, sequential), and Subscriptions (real-time push) cover all data flow patterns.
•Depth-First Execution: Resolvers execute per-field, enabling modular data fetching but requiring attention to the N+1 problem.
•Fragments Enable Composition: Reusable field selections enable DRY queries and component-colocated data requirements.
•Introspection Powers Tooling: Self-describing schemas enable IDEs, code generation, static analysis, and documentation.

What's Next:

Now that we understand how GraphQL queries work at a conceptual level, we need to examine how to define the schema that governs these queries. The schema is GraphQL's contract—the single source of truth for what queries are possible, what types exist, and how they relate. In the next page, we'll dive deep into schema design, type systems, and the principles that make schemas maintainable at scale.

Page Complete

You now understand GraphQL's query-based paradigm—how it differs from REST, how queries are structured and executed, and the three operation types that cover all data flow needs. Next, we'll explore schema definition: the type system that makes GraphQL's flexibility possible while maintaining strict contracts.