GraphQL Complete Guide: Schema-Driven API Design from Scratch

GraphQL is a query language and runtime for APIs that lets clients request exactly the data they need, eliminating over-fetching and under-fetching common in REST.

What You’ll Learn

• GraphQL core concepts: schema, queries, mutations, resolvers
• The type system: objects, scalars, enums, and relationships
• Writing queries with arguments, aliases, and fragments
• Mutations for creating, updating, and deleting data
• Architecture patterns and tooling (GraphiQL, Apollo)

Why GraphQL Matters

REST APIs force fixed response structures. To get a user and their posts, you typically need two requests (GET /users/1, GET /users/1/posts). GraphQL lets you fetch both in one request, specifying exactly the fields you need. DodaTech’s Durga Antivirus Pro dashboard uses GraphQL to fetch device details, scan history, and threat alerts in a single query — each UI component specifies its data needs without backend changes.

    flowchart LR
    A["Client App"] -->|"Single Query"| B["GraphQL API\n(You are here)"]
    B --> C["Type Definitions\n(Schema)"]
    B --> D["Resolvers"]
    D --> E["Database"]
    D --> F["REST APIs"]
    D --> G["External\nServices"]
    style B fill:#dbeafe,stroke:#2563eb
    style C fill:#fef3c7,stroke:#d97706
    style D fill:#dcfce7,stroke:#16a34a
  

GraphQL vs REST

Core GraphQL Concepts

Schema Definition Language (SDL)

GraphQL APIs are defined by a schema written in SDL:

type Device {
  id: ID!
  name: String!
  os: String!
  lastScan: DateTime
  threats: [Threat!]!
}

type Threat {
  id: ID!
  name: String!
  severity: Severity!
  detectedAt: DateTime!
}

enum Severity {
  LOW
  MEDIUM
  HIGH
  CRITICAL
}

type Query {
  device(id: ID!): Device
  threats(severity: Severity): [Threat!]!
  devices: [Device!]!
}

type Mutation {
  createDevice(name: String!, os: String!): Device!
  deleteDevice(id: ID!): Boolean!
}

Queries (Read Data)

# Request
query GetCriticalThreats {
  threats(severity: CRITICAL) {
    id
    name
    detectedAt
  }
}

# Response
{
  "data": {
    "threats": [
      { "id": "th-001", "name": "Emotet", "detectedAt": "2026-06-06T10:00:00Z" }
    ]
  }
}

Mutations (Write Data)

# Request
mutation CreateNewDevice {
  createDevice(name: "Office-PC", os: "Windows 11") {
    id
    name
    os
  }
}

# Response
{
  "data": {
    "createDevice": {
      "id": "dev-007",
      "name": "Office-PC",
      "os": "Windows 11"
    }
  }
}

Common Mistakes

1. Exposing Database Schema Directly

GraphQL types should reflect your API contract, not your database tables. Map database columns to meaningful GraphQL fields with proper naming.

2. N+1 Query Problem

Without data loaders, each nested field resolver makes a separate database query:

query { devices { threats { name } } }
// N=100 devices → 1 query for devices + 100 queries for threats = 101 queries

Use DataLoader to batch and cache database queries.

3. Ignoring Depth Limits

Malicious clients can craft deeply nested queries that overload your server. Implement query depth limits and complexity analysis.

4. Not Using Fragments

Repeating the same field selections in multiple queries is error-prone. Use fragments to reuse field selections.

5. Forgetting That Every Field Has a Resolver

If a field doesn’t have an explicit resolver, GraphQL defaults to looking for a property with the same name on the parent object. This is convenient but can cause unexpected null errors.

Practice Questions

1. What is the main advantage of GraphQL over REST?
2. What problem does the N+1 query problem cause?
3. What is the difference between a Query and a Mutation?
4. Why doesn’t GraphQL need versioning?
5. What is the purpose of DataLoader?

Answers:

1. Clients specify exactly what data they need in a single request — no over-fetching or under-fetching.
2. N+1 causes excessive database queries (1 parent query + N child queries), slowing down response times. DataLoader batches child queries into single queries.
3. Queries fetch data (parallel, cached), Mutations modify data (sequential, side effects).
4. You can add new fields and types without breaking existing queries. Clients only request what they need, so new fields don’t affect them.
5. DataLoader batches and caches database queries to solve the N+1 problem, grouping many individual lookups into batch requests.

Challenge: Write a GraphQL schema for Durga Antivirus Pro with types for User, Device, Threat, and Scan. Include queries for fetching a user’s devices and their latest threats, and a mutation for submitting a new threat report.

FAQ

Try It Yourself

Explore a live GraphQL API using the public SpaceX API:

curl -X POST https://api.spacex.land/graphql \
  -H "Content-Type: application/json" \
  -d '{ "query": "query { launches(limit: 3) { mission_name launch_date_utc } }" }'

You get back exactly mission_name and launch_date_utc — no extra fields, no multiple endpoints.

What’s Next