Two approaches to an API boundary
An API lets clients request data and trigger operations without knowing a service's internal implementation. REST and GraphQL offer different ways to design that boundary.
REST is an architectural style built around resources, representations, a uniform interface, and constraints such as stateless interactions. Many JSON-over-HTTP APIs are described as REST even when they follow only some of those constraints. GraphQL is a query language and execution model with a typed schema. Clients specify the fields they want, and the server resolves them.
Neither choice automatically produces a fast, secure, or maintainable API. Those properties depend on schema design, authorization, data access, limits, and operational practices.
A concrete example
Suppose a product page displays a product name, price, and the seller's display name. A resource-oriented API might expose:
GET /products/42
GET /sellers/7
The product response may include a seller identifier, requiring a second request. That is not inevitable: the API could embed seller details or support an explicit expansion parameter.
A GraphQL request might be:
query ProductPage($id: ID!) {
product(id: $id) {
name
price
seller {
displayName
}
}
}
GraphQL lets the client ask for nested fields in one operation. The server still has to fetch the underlying data. One network request does not imply one database query or less backend work.
Data shape and client needs
REST endpoints often return a representation selected by the server. This can keep clients simple and enable deliberate optimization for important workflows. With many clients that need different subsets of data, endpoints may accumulate variants, optional expansions, or client-specific aggregators.
GraphQL gives clients more control over response shape. A mobile app can request fewer fields while a dashboard asks for richer nested information. Schema types, introspection tooling, and generated client types can improve discoverability and development workflows.
That flexibility comes with governance work. The schema becomes a shared contract, and small client queries can hide expensive resolver behavior. Deprecating fields and monitoring actual usage are important whether the API uses REST or GraphQL.
Caching and HTTP semantics
REST APIs can use familiar HTTP mechanisms such as GET, conditional requests, ETag, and cache-control headers. A cache can reuse a safe response when the URL, authorization rules, and freshness policy allow it. Good semantics also distinguish success, invalid requests, missing resources, and conflicts through status codes.
GraphQL often uses HTTP POST for queries, which generic intermediary caches handle less naturally. Persisted queries and GET for suitable query operations can support caching, while normalized client caches store objects by identifiers. Server-side caches can also operate at resolver or data layers.
GraphQL responses can contain both data and execution errors, sometimes under an HTTP 200 response. Monitoring must inspect operation results rather than treating status codes as the entire success signal.
Performance traps
A classic GraphQL problem is N+1 fetching. Resolving a list of 100 products and then loading each seller separately can issue 101 database queries. Batch related loads and reuse request-scoped results; libraries such as DataLoader help implement this pattern. REST handlers can suffer the same database problem inside an endpoint.
For GraphQL, impose appropriate query depth, complexity, pagination, timeout, and response-size controls. Rate limiting by request count alone can miss the difference between a tiny query and a huge nested operation. For REST, watch endpoints that permit unbounded filters, expansions, or bulk operations.
Measure the entire path: network calls, database work, serialization cost, payload size, and client rendering. The API label is a poor performance benchmark.
Authorization belongs close to the data
Authentication identifies a caller; authorization decides what that caller may access. In REST, enforce authorization for the resource and its fields. In GraphQL, enforce it for objects, fields, and mutations, including nested paths to the same data.
Do not assume that hiding a button or omitting a field from one client prevents access. A client can craft another request. Apply policies consistently through shared service or data-access layers, and make errors avoid revealing confidential existence or details where that matters.
A practical comparison
| Concern | REST often fits well when… | GraphQL often fits well when… |
|---|---|---|
| Clients | Workflows and response shapes are fairly stable | Many clients need different nested views |
| HTTP integration | Generic caching and HTTP tooling are central | Schema tooling and client query control matter more |
| Operations | Endpoint costs are easy to define | Query costs can be bounded and observed |
| Team capacity | A simpler resource contract is enough | The team can own schema and resolver governance |
A backend-for-frontend can aggregate REST services into a client-specific API. GraphQL can sit above REST services, databases, or other sources. The approaches can coexist without requiring a rewrite of every service.
Start by listing actual client workflows, latency budgets, caching needs, and authorization rules. Prototype one demanding workflow and measure it. Choose the API boundary that your team can explain, secure, and evolve, rather than choosing from a popularity contest.