In a corporate web application, the API style is chosen once and then lived with for years. That decision determines the client code, caching architecture, authorization model and monitoring setup. There’s no universal right answer to “REST or GraphQL?”; but which one will cause fewer headaches under which conditions is largely predictable. Below, we compare the two approaches with concrete criteria for internal business applications and headless front ends, and give a decision tree at the end.
The core difference between the two approaches
REST isn’t a protocol but an architectural style built on top of HTTP. The system is divided into resources (order, customer, invoice); each resource has a URI, and operations are expressed with HTTP methods. The server determines the shape of the response; the client determines what it gets by choosing the endpoint. The contract is usually defined with an OpenAPI document.
GraphQL is a query language and type system. The server publishes the whole data model as a single schema; with every request, the client writes which fields it wants in the query text. For transport, usually a single HTTP endpoint (mostly /graphql) and POST are used. The schema is the contract itself and is read by tools through introspection.
The quickest way to see the difference is to model the same screen in both styles. Think of an order detail screen: the order header, lines, the customer’s name and the latest shipment status.
# REST: resource-oriented endpoints
GET /api/v1/orders/48213
GET /api/v1/orders/48213/lines
GET /api/v1/customers/9071
GET /api/v1/orders/48213/shipments?sort=-date&limit=1
# GraphQL: a single screen-oriented query
query OrderDetail($id: ID!) {
order(id: $id) {
number
date
customer { name }
lines { productCode quantity unitPrice }
lastShipment { status trackingNo }
}
}
Seeing four requests on the REST side isn’t a problem in itself; parallel requests are cheap with HTTP/2 and HTTP/3. The real question is different. Who will do the combining: the client, a purpose-built endpoint on the server, or a GraphQL resolver layer?
Client needs and data fetching
GraphQL shines when there are many clients wanting data in different shapes. If a web panel, a mobile app and a dealer portal want different subsets of the same order data, each client writes its own query instead of you writing a separate endpoint for each or returning more data than needed (over-fetching). Adding a new field to the schema doesn’t break existing clients; fields to be removed are marked with @deprecated.
REST, on the other hand, is comfortable in internal apps where the number of clients is small, data needs are stable and resources fit naturally into CRUD. Adding a GraphQL schema, resolvers and a client cache library to a request management system with a single web front end brings more moving parts than the problem it solves. This is a picture we see often in the field: a GraphQL layer set up for a three-screen app, with nobody taking on its maintenance. For a small number of screens, a few aggregating endpoints (/orders/48213?include=lines,customer or a purpose-built BFF endpoint) are usually enough.
In a headless CMS scenario, the CMS usually makes the decision: some products offer only REST, others both REST and GraphQL. We explained the choice of content layer in the what is a headless CMS and when to choose one article; here we look at the app’s own business API.
Caching and HTTP semantics
REST’s most underestimated advantage is that it uses HTTP’s caching mechanism as is. Since GET requests are identified by URI, browser, reverse proxy and CDN layers store responses according to the Cache-Control header; on a conditional request made with ETag and If-None-Match, a bodiless 304 Not Modified is returned for unchanged data. These behaviors are defined by RFC 9110 (HTTP Semantics) and RFC 9111 (HTTP Caching). No extra library is needed.
In GraphQL, since requests usually go to the same URI as POST, intermediate caches drop out. Caching moves to two places:
- Client-side normalized cache: Libraries such as Apollo Client or urql break responses down and store them by type and ID field. It’s powerful; but debugging cache inconsistency bugs is noticeably harder than with REST.
- Persisted queries: A hash is sent instead of the query text; queries can be made with GET and cached on a CDN. The same mechanism is also used as a security control that allows only pre-approved queries to run.
In corporate internal apps, data is usually user-specific and doesn’t go into a shared cache anyway. There the advantage of HTTP caching narrows. In APIs serving public data such as a product catalog, price list or content, however, REST provides significant operational convenience. The details of the headers are in the Cache-Control headers guide.
Authorization and the error model
In REST, authorization is naturally set up at the endpoint and resource level: the question “can this user read this order?” is answered in one place. In GraphQL, since a single query touches many types and fields, the check goes down to the field and object level. A sales rep may see the Customer.name field but shouldn’t see the Customer.creditLimit field. When this check is scattered across resolvers, a single forgotten field leaks data. The right pattern: apply authorization rules not in the resolvers but at a single point in the business/service layer the resolvers call. That way the same rule applies to both REST and GraphQL entry points. For role- and tenant-based authorization design, see the authorization architecture in a B2B portal article.
The error model also works differently:
| Topic | REST | GraphQL |
|---|---|---|
| Error signal | HTTP status code (400, 403, 404, 409, 422…) | The errors array in the response |
| Partial success | Usually none; the request either succeeds or fails | Yes; data and errors can be returned together |
| Standard error body | RFC 9457 Problem Details (application/problem+json) |
message, path, extensions.code |
| Monitoring | Easy metrics by status code | The errors content must be collected separately |
In GraphQL, modeling business rule errors (insufficient stock, approval limit exceeded) as result types in the schema instead of throwing them into the errors array simplifies client code; for example, a mutation returning an OrderCreated | InsufficientStock union type. In REST, the same situation is expressed with 409 or 422 and a machine-readable type field in the Problem Details body. On the monitoring side, the trap is obvious: in GraphQL, an alert that looks only at the HTTP status code never sees the error.
Performance: N+1 and query cost
GraphQL’s best-known performance trap is N+1. When a list of 50 orders is requested, if the resolver for each order’s customer field runs separately, 1 list query and 50 customer queries go to the database. Some of the tickets opened as “database slowness” are actually this. The standard solution is the DataLoader pattern, which collects individual loads within the same request and turns them into a single batch query:
// Created per request; not shared between requests
const customerLoader = new DataLoader(async (ids: readonly string[]) => {
const records = await db.customer.findMany({ where: { id: { in: [...ids] } } });
const map = new Map(records.map((c) => [c.id, c]));
return ids.map((id) => map.get(id) ?? null);
});
const resolvers = {
Order: {
customer: (order, _args, ctx) => ctx.customerLoader.load(order.customerId),
},
};
The loader must be created per request. If a single application-wide loader is used, a record loaded by one user can be returned from the cache to another user’s request who isn’t authorized for it.
The second risk is that the client can determine the query cost. Deeply nested queries (order → customer → orders → lines → product → …) wear out the server in a single request. In production, three limits should be on: a query depth limit, a field-based cost/complexity calculation and an upper bound on pagination arguments. If only your own front end uses the API, a persisted query allowlist is the strongest control. In REST the risk is more limited, because each endpoint’s cost is determined at design time. But as flexible expansion parameters such as ?include= multiply, the same limits are needed there too.
Decision tree and comparison table
Answer these questions in order; in most projects the choice becomes clear on its own:
- Will the API be exposed externally (partners, customer systems, clients in other languages)? If yes, start with REST + OpenAPI; consumers’ tool support and HTTP familiarity are the widest. The REST API versioning strategies article explains how a live API evolves.
- Do several front ends consume the same data in different shapes? If yes, and the data model is relationally rich, GraphQL is a strong candidate.
- Are the front end and back end in the same TypeScript repository, and does the API serve only this app? If yes, type-sharing RPC approaches such as tRPC or Server Actions do the job without an extra schema layer.
- Is public, cacheable data being served? If yes, REST’s compatibility with HTTP caching is decisive.
- Does the team have experience with GraphQL schema design, DataLoader and query cost control? If not, put the time to acquire this competence into the plan, or start with REST.
| Criterion | REST | GraphQL | tRPC |
|---|---|---|---|
| Contract | OpenAPI | GraphQL schema | TypeScript types |
| HTTP caching | Native | Limited, with persisted queries | Limited |
| Flexible data selection | Depends on endpoint design | Strong | Depends on procedure design |
| Authorization granularity | Resource level | Field level required | Procedure level |
| External consumers | Very suitable | Suitable | Not suitable |
| Additional operational load | Low | Medium–high | Low |
A mixed architecture is also a legitimate outcome: REST for partner integrations and file operations, a GraphQL BFF layer feeding complex screens, and a shared service layer where business rules are collected in one place. Whichever style is chosen, generate the API types for the client automatically; types kept in sync by hand drift sooner or later. We explained how to set this up in the TypeScript codebase standards article. When designing an API layer suited to your own processes, you can get support from our custom web application development or API-first and headless architecture services. For the specifications, the graphql.org learning resources and RFC 9457 are the primary sources.
Frequently asked questions
If we use GraphQL, is a REST API no longer needed at all?
It’s usually still needed. File upload and download, webhook receivers, health check endpoints and integrations opened to external partners are solved more simply with REST endpoints that use HTTP semantics directly. In many corporate systems, GraphQL for the front end and REST for integrations and file operations run side by side.
Is it normal for GraphQL responses to return HTTP 200 even when there’s an error?
Yes. Since a GraphQL response can contain both partial data and an errors array, many servers return 200 for field-level errors. Monitoring and alerting systems therefore shouldn’t look only at the HTTP status code; they should also collect the errors array and error extension codes as metrics. Returning 4xx when the request couldn’t be executed at all (a syntax or validation error) is the approach recommended by the GraphQL over HTTP draft specification.
When is tRPC a sensible choice?
If the front end and back end are developed in the same TypeScript repository, the API is consumed only by this app and there are no plans to expose it, tRPC provides type safety from client to server without writing a schema. If there are clients in different languages, partner integrations or a long-term versioning need, REST or GraphQL is more suitable.
Is it right to put a GraphQL layer in front of an existing REST API?
If the front end has to combine many REST calls, a GraphQL layer can be useful as a BFF (backend for frontend). But this layer brings risks of N+1 calls in resolvers, authorization checks duplicated in two places and added latency. First check whether the need can be met with a few purpose-built REST endpoints.