# GraphQL

A typed API query language and execution model that lets clients request the fields and relationships they need.

- Type: framework
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-24
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/graphql/>)

## What it means

GraphQL is a specification for describing an API with a strongly typed schema and executing client operations against it. Clients submit queries, mutations, or subscriptions that select fields, while server resolvers obtain the requested data. It is an API interface model, not a database or transport protocol.

## Why it matters

Product interfaces with varied data needs can evolve without adding a separate endpoint for every view. The schema creates a shared contract and supports discovery and tooling, but flexible queries shift complexity into authorization, performance control, caching, and schema governance.

## When to use it

Use GraphQL when several clients need different combinations of connected data and a team can operate a governed schema. A conventional REST-style API may be simpler for small resource interfaces, file transfer, public HTTP caching, or teams that do not need client-directed selection.

## How it works

1. Model available data and operations as types, fields, arguments, and relationships in a schema.
2. Implement resolvers that obtain each field from services or data stores while enforcing authorization.
3. Let clients send validated operations that select the precise response shape they need.
4. Execute the operation and return data together with structured errors for fields that failed.
5. Monitor field cost and usage, deprecate schema elements gradually, and control expensive queries.

## A practical example

A commerce app needs different product details on search, product, and checkout screens. One GraphQL schema lets each screen request its required fields, while query-cost limits and batched resolvers prevent an apparently small request from causing excessive database work.

## Where it breaks

GraphQL does not eliminate backend coupling or network cost. Unbounded query shapes can create unpredictable workloads, field-level authorization is easy to miss, and generic HTTP caching is less direct. Schema federation and resolver debugging add operational complexity.

## Common mistakes

- Treating GraphQL as a database and exposing internal storage models directly.
- Allowing arbitrary query depth or cost without limits and observability.
- Checking authorization only at the top-level operation instead of protected fields and objects.
- Making breaking schema changes instead of deprecating and measuring old field use.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/graphql/#visualization-graphql>)

## Sources

1. [GraphQL Specification](<https://spec.graphql.org/September2025/>) — GraphQL Foundation · Open standard
2. [Introduction to GraphQL](<https://graphql.org/learn/>) — GraphQL Foundation · Official documentation

## Related topics

- [Application Programming Interface \(API\)](<https://wiki.soroush.uk/topic/application-programming-interface/>)
- [Representational State Transfer \(REST\)](<https://wiki.soroush.uk/topic/representational-state-transfer/>)
- [API-First Design](<https://wiki.soroush.uk/topic/api-first-design/>)
