GraphQL
A typed API query language and execution model that lets clients request the fields and relationships they need.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/graphql/
01What 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.[1][2]
- 01Typed schemaTypes, fields, arguments, relationships
- 02Client operationQuery, mutation, or subscription selection
- 03Validate + authorizeSchema rules and caller permissions
- 04Execute resolversObtain fields from services or stores
- 05Data + field errorsPrecise response shape and partial failure
GraphQL is an API interface model—not a database or transport protocol. Authorization and cost controls still apply at the field and operation boundary.
02Why 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.
03When 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.
04How it works
- Model available data and operations as types, fields, arguments, and relationships in a schema.
- Implement resolvers that obtain each field from services or data stores while enforcing authorization.
- Let clients send validated operations that select the precise response shape they need.
- Execute the operation and return data together with structured errors for fields that failed.
- Monitor field cost and usage, deprecate schema elements gradually, and control expensive queries.
05A 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.
06Where 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.
07Sources
- GraphQL SpecificationGraphQL Foundation · Open standardGraphQL Specification
- Introduction to GraphQLGraphQL Foundation · Official documentationIntroduction to GraphQL