What Is GraphQL? A Developer's Explainer vs REST

If you build or consume APIs, you've almost certainly run into the question of what is GraphQL and whether it should replace the REST endpoints you already know. The short answer: GraphQL is a different way to ask a server for data. GraphQL is a query language for APIs and a runtime for executing those queries. Instead of hitting a fixed URL and taking whatever the server sends back, the client writes a query describing exactly the fields it wants, and the server returns precisely that shape.

This guide breaks down where GraphQL came from, how it works, and how it stacks up against REST so you can decide which fits your project.

Where GraphQL Came From

GraphQL isn't a startup experiment. Created by Facebook in 2012 and open-sourced in 2015, GraphQL was designed to address the data inefficiency problem of REST, particularly for mobile apps that fetch data over limited networks. The motivation was practical: the origin of GraphQL comes from Facebook's attempts to scale its mobile app. Due to issues related to high network usage and a less-than-ideal UX, the team decided to build iOS from scratch using native technologies.

The project has since outgrown its origins. Following GraphQL's transition to being made open source, the GraphQL project was moved from Facebook to the newly established GraphQL Foundation, hosted by the Linux Foundation, in 2018. That governance shift matters because it means GraphQL is now maintained as a vendor-neutral specification rather than a single company's internal tool.

A Quick Refresher on REST

To understand what GraphQL changes, you need a clear picture of REST. REST organizes an API around resources, each with its own address. REST relies on multiple endpoints, each representing a specific resource. Endpoints have fixed data structures, and clients receive the entire data structure even if they only need a portion of it.

REST leans on the plumbing of the web itself. REST APIs follow a straightforward architectural style using standard HTTP methods (GET, POST, PUT, DELETE), making them easy to understand, implement, and consume. It's also stateless by design: REST APIs achieve statelessness by ensuring that each request from the client to the server must contain all the information required to understand and process the request. The server does not retain any session information about the client.

One of REST's quieter strengths is that it rides on standard web caching. REST APIs can take advantage of HTTP caching mechanisms, reducing server load and improving response times for repeated requests. Keep that in mind — it's a real edge REST holds over GraphQL, which we'll return to.

How GraphQL Works

GraphQL flips the resource model. Rather than a directory of endpoints, it presents one door. GraphQL uses a single endpoint and allows clients to specify their data requirements, while REST relies on multiple endpoints with fixed data structures. In practice, rather than exposing multiple endpoints, GraphQL exposes a single endpoint. Clients send a query specifying exactly what data they need, and the server returns only that data.

That behavior is enabled by a schema. A GraphQL server defines a schema, which describes types (like User, Product, Order) and their relationships. The schema is the contract between client and server, and it's strictly enforced. GraphQL's strongly typed schema provides clarity and validation, catching errors early in the development process.

Because the schema is machine-readable, a GraphQL API can describe itself. Due to its strong type system, GraphQL gives you the ability to query and understand the underlying schema. The Introspection feature allows you to query the schema and discover the available queries, mutations, subscriptions, types and fields in a specific GraphQL API. This is what makes tools like schema explorers and autocomplete-aware editors possible, and it's why GraphQL APIs are often called self-documenting.

Queries, Mutations, and Subscriptions

GraphQL organizes everything a client can do into three operation types. Queries read data. Mutations write it — mutations modify data (create or update records). The third type handles real-time data. In addition to reading and writing data using stateless query and mutation operations, the GraphQL specification also describes how to receive real-time updates via long-lived requests.

Subscriptions are worth understanding before you commit to them, because they carry infrastructure implications. GraphQL subscriptions are typically backed by a separate pub/sub system so that messages about updated data can be published as needed during runtime and then consumed by the resolver functions for the subscription fields in the API. The spec doesn't mandate how you move those messages over the wire: GraphQL doesn't specify what transport protocol to use, so it's up to the server to decide. In practice, you will often see them implemented with WebSockets or server-sent events.

GraphQL vs REST: The Core Trade-off

The headline difference is who controls the response shape. With REST's fixed structures, you frequently get too much data or too little — the classic over-fetching and under-fetching problems. GraphQL's client-driven model targets exactly that. This client-driven approach eliminates over-fetching and allows the retrieval of multiple resources in a single request.

That single-request behavior is the performance argument for GraphQL. GraphQL's ability to fetch all required data in a single request can lead to improved performance by reducing the number of round trips between the client and server. REST APIs may require multiple requests to fetch related resources, which can impact performance. On a mobile connection, collapsing five round trips into one is a tangible win.

REST fights back on caching and simplicity. REST's simplicity can make it faster in straightforward scenarios, especially when responses can be cached. But when clients need multiple related resources, GraphQL's single-request model often wins. Because REST maps neatly onto cacheable HTTP GET requests, off-the-shelf caching layers work with little effort — something GraphQL's single POST-to-one-endpoint model makes harder.

The Downsides GraphQL Doesn't Advertise

Flexibility has a cost. The most infamous is the N+1 query problem. In a naive implementation, the GraphQL server fetches each author, then performs an additional query to fetch related books for each author, leading to 1 + N queries where N is the number of authors. Left unchecked, that pattern hammers your database. The common fixes are batching and caching at the data layer — often via a DataLoader utility — plus persisted queries: storing and reusing common queries can significantly drop the number of redundant database operations. By assigning unique identifiers to these queries, the server anticipates the necessary data fetch operation, thus minimizing the risk of N + 1 issues.

Introspection is another double-edged feature. The same self-documenting capability that helps developers can help attackers. The Schema Introspection is a great feature and it can be really helpful, but it can cause problems too. That means potential attackers can get a good understanding of your API and they can even get access to resources that are not meant to be publicly available. In production, many teams disable or lock down introspection for exactly this reason.

Which One Should You Use?

There's no universal winner — the decision comes down to your data shape and client mix. GraphQL is well-suited for complex data needs, multiple client types, and evolving APIs. REST is a good fit for simple and static data, incremental adoption, and leveraging existing REST expertise.

A useful way to frame it: if you're serving one predictable client and a handful of stable resources, REST's simplicity and free HTTP caching are hard to beat. If you're feeding web, iOS, and Android clients that each need different slices of deeply related data, GraphQL's single flexible endpoint pays for its added complexity. Many organizations run both — REST for straightforward services and GraphQL as an aggregation layer over them. If you're weighing broader infrastructure choices, our comparison of Kubernetes vs Docker Swarm follows a similar trade-off-driven approach.

The bottom line: GraphQL isn't a replacement for REST so much as a different set of trade-offs. Understand the schema, the single-endpoint model, and the caching and N+1 caveats, and you'll know when reaching for it actually solves a problem instead of adding one. For more explainers like this, browse our Dev Tools coverage, and if you're building AI-driven services on top of your API, see our guide to prompt engineering.