Skip to content

CONCEPT Cited by 1 source

Unified Graph (Principled GraphQL)

Definition

A unified graph is an organisational discipline that treats the GraphQL schema as one shared surface across the entire company — not one graph per team, per product, or per client. All frontend clients (Web, iOS, Android, partner APIs, internal tooling) query the same schema; all domain teams contribute fields and resolvers to it. The term comes from Apollo's Principled GraphQL manifesto, whose first principle is explicitly "One Graph".

What it replaces

Before the unified-graph approach, large organisations accumulated:

  • Many Backend-for-Frontend services (BFFs), one per surface.
  • Fragmented schemas — a mobile API with one type graph, a web API with a different one.
  • Duplicated logic — the same aggregation built in multiple services with drift.
  • Inconsistent customer experience — subtly different behaviour across surfaces (Zalando's canonical example: different delivery-window computations yielding "5-9 Feb" on mobile and "1-3 Feb" on desktop).

One Graph is the discipline: one schema, one service surface, every client queries the same shape.

The core tension: one service vs many

"One graph" is a schema-level commitment. How it gets implemented at the service layer is an orthogonal choice:

Implementation Example Trade
Single monolith service Zalando UBFF Simpler ops + unified tooling; at the cost of per-domain deploy independence
Federated subgraphs Apollo Federation, Netflix DGS Per-domain deploy independence; at the cost of runtime composition complexity
Schema stitching (historic) Early Apollo Deprecated — composition issues at scale

Both monolith and federation are valid one-graph implementations. The schema is one; the runtime topology varies.

Canonical organisations operating a unified graph

All named in Zalando's 2021 post (Source: sources/2021-03-03-zalando-how-we-use-graphql-at-europes-largest-fashion-e-commerce-company):

  • GitHub — single GraphQL API covering repos, users, marketplace.
  • Shopify — two unified graphs (StoreFront for customers, Admin for merchants).
  • Airbnb — working on unified schema (GraphQL Summit 2019 talk).
  • Expedia — migrated from REST to a central data graph; the motivating observation was "developers spent more time figuring out which service to call than shipping features."
  • Netflix — one-graph in the Studio ecosystem (systems/netflix-enterprise-graphql-gateway).
  • Zalando — Unified Backend-For-Frontends (systems/zalando-graphql-ubff).

What unified-graph discipline implies

  1. Field-level deprecation is the norm, not breaking version bumps. If any client can query any field, the schema cannot casually remove anything.
  2. Schema governance becomes a load-bearing function. Someone has to own naming, consistency, cross-domain entity identity, and deprecation cadence.
  3. Schema-design consultation becomes a platform-team responsibility. Zalando describes this explicitly: their GraphQL team runs "consultation" hours for new domains integrating into the graph, "since GraphQL schema design is always a tricky topic."
  4. Entities become first-class. A unified graph succeeds when there is a shared set of named entities (Zalando: Product, Campaign) that multiple domains contribute to, cross-linked into a "dense graph."
  5. Documentation is a single artefact. Zalando's one-stop docs site has embedded GraphiQL + Voyager + practice exercises; you can't have N docs sites for a single graph.

The subtle Conway's-Law inversion

Fragmented BFFs exist because the org is fragmented — Conway's Law pushes architecture to mirror the org chart. A unified graph requires the opposite: a deliberate architectural commitment ("one graph across everything") that forces cross-team coordination the org chart wouldn't otherwise demand. This is Inverse Conway applied to the API surface.

Seen in

Last updated · 476 distilled / 1,218 read