GraphQL

GraphQL is a query language for APIs and a server-side runtime for executing those queries, developed by Facebook in 2012 and open-sourced in 2015. Unlike REST, where the server defines fixed resource shapes at fixed URLs, GraphQL exposes a single endpoint and lets clients describe the exact shape of the data they need.

Core concepts:

Schema Definition Language (SDL): the contract between client and server.

type User {
  id: ID!
  email: String!
  posts: [Post!]!
}
type Post {
  id: ID!
  title: String!
  author: User!
}
type Query {
  user(id: ID!): User
  posts(limit: Int = 10): [Post!]!
}
type Mutation {
  createPost(title: String!, authorId: ID!): Post!
}
type Subscription {
  newPost: Post!
}

Operation types:

Type	Description	Analogy
Query	Read data	HTTP GET
Mutation	Write or modify data	HTTP POST/PUT/DELETE
Subscription	Real-time event stream via WebSocket	SSE / WebSocket

Resolvers: server-side functions that fulfill each field in the schema. Each field maps to a resolver; resolvers compose to build the response tree.

The N+1 problem: a common performance trap where fetching a list of users triggers a separate database query per user to fetch related posts. Solved by DataLoader (batching and caching resolver calls within a single request).

Introspection: clients can query the schema itself (__schema, __type) to discover available types and fields, enabling tooling like GraphiQL and Apollo Explorer.

Persisted queries: hash a query string and send only the hash in production, reducing payload size and enabling server-side query allowlisting.

# Query: request only the fields the client needs
query GetUserWithPosts($userId: ID!) {
  user(id: $userId) {
    email
    posts {
      title
    }
  }
}

# Mutation: create a new resource
mutation CreatePost($title: String!, $authorId: ID!) {
  createPost(title: $title, authorId: $authorId) {
    id
    title
  }
}

# Subscription: receive real-time updates
subscription OnNewPost {
  newPost {
    id
    title
    author { email }
  }
}

# Introspection: discover the schema
query IntrospectTypes {
  __schema {
    types {
      name
      kind
    }
  }
}

# Send a GraphQL query via curl
$ curl -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "query { user(id: \"123\") { email posts { title } } }"
  }'

# GitHub GraphQL API v4: get repo details
$ curl -X POST https://api.github.com/graphql \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -d '{
    "query": "{ repository(owner: \"torvalds\", name: \"linux\") { stargazerCount forkCount } }"
  }'