What GraphQL Changes About API Design

Most developers who have worked with web APIs are familiar with REST. REST (REpresentational State Transfer) is a software architecture style introduced by Roy Fielding in 2000 that lays out principles for how a web application should behave. Among its core ideas: each endpoint should handle one CRUD operation, and each response has a fixed shape. That fixed-shape approach is convenient but limiting—sometimes a client needs less data than an endpoint returns, and sometimes it needs more, which forces additional calls. GraphQL, an open-source data query and manipulation language publicly released by Facebook in 2015, addresses this by letting clients describe exactly the data structure they want, all under a single endpoint.

Key Terms for API Beginners

If you are new to API development, a few definitions will be useful before diving deeper.

API

An Application Programming Interface (API) lets two machines talk to each other. Think of it as the cashier who takes your order to the kitchen and brings back your meal. APIs matter because they let multiple devices, such as your laptop and phone, talk to the same backend server.

REST

REST is a software architecture style describing how a web application should behave. It handles different types of calls and responses and breaks resources down into CRUD services, making it easier to organize endpoint responsibilities. A key REST principle is client-server separation of concerns—server-side problems remain server-side, while the client simply waits for a response to its request.

Latency Time

Latency time is how long a request takes to travel to the server. Like driving from point A to point B, traffic can cause delays. Lower latency means faster request processing; higher latency means slower processing.

Response Time

Response time is latency plus the time the server takes to process the request. Think of it as the total time from placing an order to receiving it. Faster response times make for a more seamless user experience; slow ones can drive users away.

REST's Over- and Under-Fetching Problem

A RESTful endpoint returns the same fixed set of data every time, regardless of what the client actually needs. That cookie-cutter response often means clients either pull extra data they don't need (over fetching) or have to make additional API calls to gather missing pieces (under fetching).

Consider a team, its championships, and its players. If you want the founding year, the captain's first and last name, and the last championship date, you would need three separate RESTful calls:

Understanding GraphQL for Beginners–Part One

Each call is a separate trip to the server and back. Latency times differ between calls—just like traffic varies by route and time of day. If one call is slow, the total response time suffers. GraphQL lets you combine all three requests into one trip and receive precisely the data you asked for.

Two Analogies for GraphQL

The Burger Order

Picture a restaurant where ordering a double cheeseburger always delivers the same complete burger: same ingredients, same proportions. That is a RESTful call. Maybe you do not want pickles, or you want the cheese unmelted and the bacon on top. With GraphQL, you describe your burger exactly the way you want it—fewer pickles, sautéed onions on the bottom, no sesame seeds on the bottom bun—and the kitchen returns precisely that.

An image of a two pattie hamburger on a sesame seed bun with cheese, bacon, pickles, red pepper, and secret sauce
Photo by amirali mirhashemian on Unsplash.

Your GraphQL response is shaped exactly by your description.

A two pattie hamburger on a sesame seed bun with cheese, bacon, pickles, red pepper, and secret sauce
Photo by amirali mirhashemian on Unsplash.

The Bank Withdrawal

Now imagine requesting a $200 withdrawal. A RESTful API might always hand you two $100 bills, no matter what you ask for. GraphQL lets you specify the denominations—one $100 bill and five $20 bills, for instance.

An image of two rectangles side by side. Each rectangle represents $100 and that text is contained within each rectangle.
Two $100 bills
An image of six rectangles in a three by three grid. The first rectangle starting from the top left represents $100 and the other five represent $20 from the text contained within each rectangle.
One $100 bill and five $20 bills

Core Benefits Over REST

GraphQL offers four main advantages compared with RESTful APIs:

  1. No over fetching. REST returns a fixed-size shape even when the client needs only part of the data. GraphQL clients request only what they need.
  2. No under fetching. When a REST endpoint lacks needed data, clients must make additional calls. GraphQL queries can pull all required data in one request.
  3. Faster front-end iteration. The flexible, client-driven structure means frontend developers can change UI needs without asking backend developers to adjust endpoints for every design shift.
  4. Fewer endpoints. Tracking many REST endpoints gets confusing. GraphQL's single, "smart" endpoint can handle what would otherwise require multiple RESTful actions.

By letting clients describe the exact structure of the data they want back, GraphQL avoids multiple round trips for fixed, cookie-cutter responses. A follow-up guide walks through implementing GraphQL in a Ruby on Rails application and creating and executing queries.