REST organizes operations around HTTP resources and endpoints. GraphQL exposes a typed schema that lets clients select fields through queries and mutations. GraphQL can reduce client-specific endpoint growth, while REST can preserve simpler HTTP behavior and operations. The right choice depends on clients, domain shape, team skills, performance controls, and existing systems, and a product may use both.
Who this is for: Product engineers and technical leads choosing an API style for a real application rather than following a technology trend.
- Compare the styles against measured client workflows and operational constraints, not request-count slogans.
- Budget for authorization, query cost, caching, observability, and schema evolution whichever style you choose.
- A mixed architecture is valid when boundaries are explicit and duplicate domain logic is avoided.
The styles expose different contracts
A REST API commonly maps URLs and methods to resource operations and returns server-defined representations. HTTP caches, statuses, conditional requests, and content negotiation fit naturally. A client that needs a new combination of related data may make several requests, accept extra fields, or ask the server for a purpose-built representation.
GraphQL publishes a schema of types and fields, usually through one HTTP endpoint. A query states the response shape and can traverse relationships. That flexibility helps multiple clients with different views, but it moves complexity into schema design, resolver execution, query controls, and tooling. It does not remove backend service calls or database work.
Client flexibility has a server cost
GraphQL can let mobile and web teams request only the fields they need and evolve views without waiting for a new endpoint. Typed tooling can improve discovery and catch invalid queries. These benefits are strongest when many trusted clients need overlapping but distinct graphs of data and schema ownership is disciplined.
The server must prevent expensive queries, repeated resolver loads, excessive depth, and broad field access. Batching can address repeated data fetches, while persisted operations, depth or complexity budgets, timeouts, and pagination limit abuse. Field-level authorization must be explicit. Hiding an unauthorized field in one resolver does not secure related paths automatically.
REST often keeps operations legible
REST can be easier for bounded public operations, file transfer, webhooks, and resources that benefit from ordinary HTTP caching. Endpoint-level metrics and access rules are often straightforward. It can also become inconsistent when teams add ad hoc endpoints, return oversized representations, or require clients to orchestrate multi-step workflows without transactional support.
Neither request count nor payload size determines the winner alone. One GraphQL query can trigger hundreds of backend reads, while several cacheable REST requests may be cheap. Conversely, a mobile client on a high-latency connection may benefit from one carefully bounded GraphQL operation. Measure end-to-end latency, server work, cache hit rate, and failure behavior.
Choose with organizational evidence
List current clients, upcoming views, public versus trusted access, ownership boundaries, and operational skills. Prototype one representative read and one consequential write in each viable style. Include authorization, pagination, errors, traces, and load testing, not just the happy query. Estimate migration and long-term support rather than comparing greenfield demos.
Teams can place GraphQL as a product-facing aggregation layer while services retain REST or event interfaces. That can work if domain rules remain in owned services and the graph does not become an unaccountable second backend. Avoid operating two public styles for the same capability unless a transition or clear consumer need justifies the cost.
Evaluate an issue dashboard API
A product has web, mobile, and partner clients that need issue details, labels, assignees, and activity in different combinations.
- Write representative client screens and record fields, relationships, latency budgets, cache needs, and write operations.
- Prototype REST resources with conditional caching and a GraphQL query with pagination, batching, and query-cost limits.
- Apply the same authorization cases, including private fields and cross-project references, to both prototypes.
- Measure client round trips, transferred bytes, resolver or endpoint work, error visibility, and operational complexity.
- Choose the style whose total cost fits the clients and team, while documenting where the alternative remains useful.
API style decision table
Score evidence for the specific product instead of assigning universal winners.
- Consumers: number, trust level, release independence, data-shape variation, and network constraints.
- Domain: relationship depth, transactional commands, file or stream needs, and ownership boundaries.
- Operations: caching, query cost, rate limits, tracing, error diagnosis, and abuse prevention.
- Organization: schema or endpoint governance, skills, tooling, migration effort, and support capacity.
- Prototype evidence: representative latency, backend work, bytes, failure modes, and authorization tests.
Common mistakes
- Choosing GraphQL solely to eliminate over-fetching without measuring resolver cost or cache behavior.
- Calling REST simple while exposing inconsistent endpoints and client-managed business transactions.
- Running both styles indefinitely with separate authorization and domain logic that drift apart.
Try one
A small team serves one web client and a public integration API. Data relationships are shallow, but partners value cacheable stable resources. Recommend an approach and name evidence that could change it.
A reasoned recommendation starts with REST because the consumer set, shallow resources, HTTP caching, and public contract favor a smaller operating surface. It should not claim GraphQL is wrong. More first-party clients with rapidly varying graph-shaped views, measured round-trip problems, and capacity to govern query cost and field authorization could justify a GraphQL layer later.
Sources
- GitHub GraphQL API documentationGitHub's primary overview of its GraphQL schema and query model.
- GitHub REST API documentationGitHub's primary documentation for REST API requests, resources, and versioning.
- MDN HTTP overviewMDN's overview of HTTP messages, connections, intermediaries, and browser behavior.