GraphQL Origins

  • Created: Facebook, 2012 (internal), open-sourced 2015
  • Why: Mobile app needed to fetch exactly what it needed—no more, no less
  • Name: Graph Query Language—models data as a graph of connected nodes

GraphQL vs REST: Key Differences

  • Endpoints: REST has many (/users, /posts), GraphQL has ONE (/graphql)
  • Over-fetching: REST returns everything; GraphQL returns exactly what you ask for
  • Under-fetching: REST needs multiple calls; GraphQL gets related data in one query
  • Versioning: REST uses /v1, /v2; GraphQL evolves schema without versions
  • Caching: REST uses HTTP caching; GraphQL needs custom solutions (Apollo, Relay)

Query, Mutation, Subscription

  • Query: Read data—like GET in REST. Can fetch nested related data in one call
  • Mutation: Write data—like POST/PUT/DELETE. Returns updated data immediately
  • Subscription: Real-time updates via WebSocket. Great for chat, notifications, live feeds

Schema Design Best Practices

  • Use descriptive type names: User, not U or UserType
  • Nullable by default—add ! only when truly required (easier migrations)
  • Use interfaces for shared fields (Node, Timestamped, Auditable)
  • Prefer connections over arrays for pagination: users(first: 10, after: cursor)
  • Add descriptions: """User account with profile and settings""" for documentation

Who Uses GraphQL?

  • GitHub API v4: Entire public API is GraphQL (REST is v3, legacy)
  • Shopify: Powers their entire storefront and admin APIs
  • Airbnb: Migrated from REST to reduce mobile data usage by 30%
  • Twitter: Uses it for their web app data fetching
  • Netflix, PayPal, Pinterest, Starbucks, The New York Times...

Common Gotchas

  • N+1 problem: Use DataLoader to batch database queries
  • Security: Limit query depth and complexity to prevent DoS
  • No file uploads in spec: Use multipart form data or presigned URLs
  • Error handling: Errors can be partial—check both data AND errors fields
  • Introspection: Disable in production to hide your schema from attackers

Tooling Ecosystem

  • Apollo: Most popular client and server libraries
  • Relay: Facebook's client, strict but powerful
  • Hasura: Instant GraphQL API from PostgreSQL
  • Prisma: Database toolkit that generates GraphQL resolvers
  • GraphiQL/Playground: Interactive IDE for exploring APIs