GraphQL

What is GraphQL?

GraphQL is a query language and runtime for APIs, created by Facebook, that inverts who decides what data a response contains. Instead of the server defining fixed endpoints that return fixed shapes (as in REST), the client sends a query specifying exactly the fields it wants, and the server returns precisely that — no more, no less — from a single endpoint. It’s the answer to two chronic REST pains: over-fetching (getting fields you don’t need) and under-fetching (having to call three endpoints to build one screen).

The problem it solves — and the problems it creates

The canonical motivating case is a mobile screen that needs bits of data from several resources: with REST that’s multiple round-trips or a custom endpoint; with GraphQL it’s one query that pulls user, orders, and recommendations together, fetching only the fields the screen renders. This is genuinely powerful for complex, fast-evolving frontends and for exposing a graph of interconnected data. But GraphQL is not free lunch — it trades REST’s simplicity for a new class of problems. Caching is harder: REST leans on HTTP caching by URL, while GraphQL’s single endpoint and variable queries need application-level caching. The N+1 query problem is notorious: a naive resolver fetching nested data can fire a database query per item, which is why DataLoader-style batching is near-mandatory. And a public GraphQL endpoint invites expensive/malicious queries (deeply nested or wide requests), so query cost analysis, depth limiting, and rate limiting become necessary defenses.

When to reach for it — and when not to

Honest guidance: GraphQL earns its complexity when you have many clients with differing data needs (web, mobile, partners) hitting a rich, interconnected data model that changes often. For a simple CRUD API, a handful of endpoints, or a public API where broad tooling and HTTP caching matter, REST is usually the better, simpler choice. For high-performance internal service-to-service calls, gRPC often fits better. The mistake in both directions: adopting GraphQL for a simple app and drowning in resolver/caching complexity, or forcing REST on a frontend that genuinely needs flexible, client-driven fetching.

What people get wrong

• The N+1 problem — naive resolvers issue a query per nested item; batching (DataLoader) is essential, not optional.
• No query protection: public GraphQL without depth limits and cost analysis invites accidental or malicious expensive queries.
• Adopting it for simple apps — the caching and tooling overhead only pays off when clients genuinely need flexible data shapes.

Primary source: GraphQL specification and docs