Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 3 · Lesson 20 · 3 min read

GraphQL vs REST: Which Should You Use?

On this page
  1. GraphQL vs REST is not a contest
  2. GraphQL vs REST compared side by side
  3. Three scenarios: which API style fits?
  4. Using REST and GraphQL together
  5. Four questions to decide between REST and GraphQL
  6. Check yourself

GraphQL vs REST is not a contest

GraphQL isn't "the new REST", and REST isn't outdated. They make different trade-offs. Many companies run both: REST for public and partner APIs, GraphQL as the layer their own apps talk to.

GraphQL vs REST compared side by side

RESTGraphQL
Data shapeFixed per endpoint, chosen by the serverChosen per query by the client
Round trips for a complex screenOften severalUsually one
HTTP caching and CDNsNatural: GET by URLNeeds persisted queries or client-side caches
ErrorsHTTP status codesUsually 200 with an errors array; partial success possible
ContractOpenAPI (optional)Schema (required), with introspection
VersioningOften /v1, /v2Usually continuous evolution with deprecations
Rate limitingPer requestPer query cost
File uploads, streaming downloadsSimpleAwkward; often a separate REST endpoint
Security surfacePer routePer field and object, plus query cost
Learning curveLower; any HTTP client worksHigher; schema, resolvers, tooling
REST fits stable, cacheable, resource-oriented APIs; GraphQL fits client-driven apps assembling varied data from many sources.
REST fits stable, cacheable, resource-oriented APIs; GraphQL fits client-driven apps assembling varied data from many sources.

Three scenarios: which API style fits?

A public payments API for thousands of developers. Integrators use every language and tool; HTTP caching, simple webhooks and clear status codes matter; the operations are stable (create a charge, refund). REST, with OpenAPI docs and SDKs generated from them. Stripe made this choice.

A product with web, iOS and Android apps, each screen combining data from users, orders, recommendations and inventory services. Screens change every sprint; mobile networks are slow. GraphQL as the client-facing layer, with resolvers calling the services. Clients fetch exactly what each screen needs in one request, and frontend teams ship without waiting for backend endpoints.

Internal service-to-service calls with high throughput. Neither is ideal: gRPC with Protocol Buffers gives typed contracts, efficient binary encoding and streaming (see the gRPC course). REST is fine when simplicity matters more than efficiency.

Using REST and GraphQL together

A common, effective architecture:

  • Domain services expose REST or gRPC internally.
  • A GraphQL layer (or a backend-for-frontend, Day 21) composes them for the company's own apps.
  • Public partners get a REST API with stable, versioned endpoints and webhooks (Day 25).
  • Large organizations use GraphQL federation (Apollo Federation, GraphQL Mesh, WunderGraph Cosmo) to let each team own part of one combined graph.

Four questions to decide between REST and GraphQL

  1. Who are the clients? Many external developers favor REST; your own varied apps favor GraphQL.
  2. How varied are the data needs? Fixed, simple operations suit REST; many screens with different shapes suit GraphQL.
  3. How important is HTTP caching? Public, cacheable content leans REST.
  4. Can the team operate it? GraphQL needs schema governance, query-cost limits and resolver performance work.

Check yourself

Every language and tool supports it, HTTP caching and status codes work naturally, and fixed endpoints are easy to document and version.

Each screen fetches exactly the fields it needs across several sources in one request, saving round trips on slow networks.

HTTP caching, since queries usually go by POST to one URL; cost-based rate limiting, since one request can be cheap or enormous; file uploads; and monitoring, since errors often arrive with a 200 status.

Yes. Many companies offer REST for public partners and webhooks, and GraphQL for their own apps, both backed by the same services.

Who the clients are, how varied their data needs are, how important HTTP caching is, and what the team already knows how to run.