GraphQL

GraphQL is a declarative query language and runtime for APIs. Instead of exposing a set of fixed endpoints that each return a fixed shape of data, a GraphQL server publishes a strongly typed schema, and clients send queries that describe exactly which fields they want. The server walks the query against the schema, calls the appropriate resolver functions, and returns a JSON response whose shape mirrors the query.

Although it borrows ideas from SQL, REST, and JSON, GraphQL is its own thing: a small, focused language for describing API shapes and the requests that traverse them. Since its public release in 2015, it has grown into one of the most widely adopted API technologies of the last decade, with implementations in essentially every popular programming language.

History and Origins

GraphQL was created inside Facebook in 2012, as part of an effort to rebuild the company’s native mobile applications. The existing REST-based news feed API forced the mobile clients to make many requests and to over- or under-fetch data, and the engineering team — including Lee Byron, Nick Schrock, and Dan Schafer — designed a new query language that let the client describe its data needs declaratively in a single request.

The language was used internally at Facebook for several years before being publicly announced at React.js Conf in 2015. Alongside the announcement, Facebook published a draft specification and graphql-js, a JavaScript reference implementation that doubled as a working server library.

Adoption outside Facebook was rapid. GitHub’s 2016 announcement that its next API would be GraphQL signaled that the technology was viable for large public APIs. The Apollo project provided ergonomic client and server tooling for the broader JavaScript ecosystem, and implementations soon appeared in Ruby, Python, Java, Go, Elixir, Rust, C#, and many other languages.

In 2018, stewardship of GraphQL moved from Facebook to the GraphQL Foundation, a project under the Linux Foundation, putting the specification on a vendor-neutral footing similar to projects such as Kubernetes and Node.js.

Design Philosophy

GraphQL is shaped by a small set of opinions:

• Ask for exactly what you need. Clients specify the fields they want, including nested fields across related types, in a single query. The server returns a JSON document with precisely that shape — no more, no less.
• One endpoint, many queries. A GraphQL service typically exposes a single HTTP endpoint. Different operations are distinguished by their content, not their URL.
• Types are first-class. Every field has a type, declared in the schema. Tools, IDEs, and clients can introspect the schema to provide autocomplete, validation, and documentation.
• Resolvers separate shape from source. The schema describes what data exists; resolver functions describe where each field comes from. This decouples the public API surface from the underlying storage or service architecture.
• Backwards-compatible evolution. Fields can be added freely; deprecation is built into the language. There is no API versioning by URL in idiomatic GraphQL — the schema evolves in place.

Key Features

• Schema Definition Language (SDL) — A concise textual notation for declaring types, fields, enums, interfaces, unions, and input types.
• Queries — Read-only requests that fetch data, with support for arguments, aliases, fragments, and variables.
• Mutations — Write operations that change server-side state and return a result shaped by the client’s selection set.
• Subscriptions — Long-lived operations that push updates to the client when underlying data changes, typically delivered over WebSockets.
• Introspection — A built-in mechanism that lets clients query the schema itself; this powers tools like GraphiQL, GraphQL Playground, and IDE plugins.
• Directives — Annotations such as @include, @skip, and @deprecated, plus custom directives, that modify execution or describe metadata.
• Fragments — Reusable selection sets that promote DRY queries, especially in UI code where multiple components share fields.

A Small Example

A schema for a tiny blogging API might look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
  comments: [Comment!]!
}

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

type Query {
  post(id: ID!): Post
  feed(limit: Int = 10): [Post!]!
}

A client that wants a post title plus the names of its commenters can ask for exactly that:

1
2
3
4
5
6
7
8

query {
  post(id: "42") {
    title
    comments {
      author { name }
    }
  }
}

The response is a JSON document whose shape matches the query — a property GraphQL calls isomorphism between query and response.

Evolution

The core ideas have been stable since 2015, but the ecosystem has evolved substantially:

• Tooling — Editors, IDEs, and language servers gained deep GraphQL awareness; introspection and schema files made code generation routine.
• Federation — Apollo Federation (2019) and competing approaches such as schema stitching and, more recently, GraphQL composite schemas efforts at the GraphQL Foundation, address how to compose many services into one graph.
• Transports — The GraphQL over HTTP working group has worked to standardize what had been a de facto convention (POST with a JSON body containing query, variables, and operationName), and GraphQL over WebSocket and Server-Sent Events specifications have brought order to subscription transport.
• Persisted queries and trusted documents — To reduce payload size and improve security, many large deployments now ship pre-registered query IDs rather than raw query strings.
• Specification cadence — The specification has moved to dated editions; the October 2021 edition is the most recently ratified at the time of writing, with ongoing drafts in the working group.

Current Relevance

GraphQL is a fixture of modern API design. Major platforms — GitHub, Shopify, Meta, and many others — expose GraphQL APIs to external developers, and internal “data graph” architectures are common at companies operating large numbers of microservices.

It has not displaced REST: simple resource-oriented APIs are often easier to build and cache with REST, and HTTP-level caching is still more straightforward there. But for applications with rich, interconnected data — especially mobile and single-page web applications — GraphQL’s ability to fetch exactly the data a screen needs in one round trip remains a strong draw.

The community is large and active, with major conferences (GraphQL Conf), a working group that meets regularly, and a long list of server and client implementations in nearly every mainstream programming language.

Why It Matters

GraphQL is one of the clearest recent examples of a small, well-chosen domain-specific language reshaping a corner of software engineering. By treating an API as a typed graph and a request as a declarative selection over that graph, it changed how teams think about the contract between client and server: not as a catalog of endpoints, but as a single, evolving schema describing the data their product is built from.

Its influence reaches beyond its own ecosystem. Schema-first design, code generation from typed contracts, and the idea that clients should be able to introspect their APIs at runtime have all been reinforced — if not pioneered — by GraphQL’s mainstream success, and the language is now a standard part of the modern API designer’s vocabulary.