GraphQL

GraphQL is a query language and server-side runtime for APIs that lets clients specify exactly which fields they need in a single request, rather than being handed a fixed response shape by the server. It was created at Facebook in 2012, open-sourced in 2015, and is now maintained by the GraphQL Foundation under the Linux Foundation, with its specification published at spec.graphql.org.

How it works

A GraphQL API exposes a single endpoint backed by a strongly typed schema, written in Schema Definition Language (SDL), that declares every object type and the fields it has. Clients send a query shaped like the response they want:

type Book {
  title: String!
  author: String!
}

query {
  book(id: "1") {
    title
  }
}

The server resolves each field independently via a resolver function, so a query nesting author { books { title } } fans out to multiple resolver calls but returns as one JSON response, shaped exactly like the query. The schema defines three root operation types: Query (read), Mutation (write), and Subscription (real-time updates over a persistent connection).

Why it matters

GraphQL's main pitch over REST is avoiding over-fetching (getting a payload with fields you don't need) and under-fetching (needing several round-trips to assemble one view). A JSON payload that already looks like a nested object graph — the output of a tool like JSON to GraphQL — maps naturally onto a GraphQL schema, since both share the same tree-shaped data model.

Common pitfalls

• A single deeply nested query can still cause the same N+1 database-query problem REST has — the fix (batching/dataloaders) lives in resolver code, not the query language itself.
• GraphQL always returns HTTP 200, even for errors — clients must check the response body's errors array, not the status code.
• Because clients choose the shape of every response, naive GraphQL servers are easier to abuse with expensive, deeply nested queries — production servers need query depth/complexity limits.
• GraphQL's flexibility doesn't remove the need for authorization checks per field — a common mistake is authorizing the top-level query but not nested fields it exposes.

Related terms

• JSON — the format GraphQL responses are almost always serialized as.
• XML — the older, more rigid format some legacy GraphQL alternatives (like SOAP) predate GraphQL with.

See also

• Tool: JSON to GraphQL — generate GraphQL SDL types directly from a JSON sample.