REST and GraphQL are the two answers most teams pick between when designing an API in 2026. The honest read: REST is the right default for most product APIs, GraphQL is a real fit for a narrower set of use cases, and the "which is better" debates usually obscure that the right answer depends on who reads your API and what they do with it.
This is the short, opinionated version.
The one-line summary
- REST is a set of conventions over HTTP. Resources, status codes, predictable URLs, easy to cache, every HTTP client speaks it.
- GraphQL is a single endpoint that takes a query language. The client says exactly what fields it wants, the server returns exactly that.
Both can be perfectly good. They optimize for different things.
Where REST wins
1. Customers integrate it without a special client.
Anyone with curl, a Postman collection, or a five-line fetch call can use a REST endpoint. There is no client library required. For an API whose customers range from a senior engineer at one company to a junior on a hackathon team, that floor matters.
2. Caching is mostly free.
HTTP caching (CDN, browser, reverse proxy) works because URLs are addressable. GET /messages/123 can be cached for 60 seconds by a CDN with zero application code. GraphQL has a single POST endpoint; HTTP caching does not help you out of the box.
3. Tooling is mature.
OpenAPI 3.1 specs, every SDK generator (Bloom, Stainless, Speakeasy, OpenAPI Generator, etc.), every docs platform, every monitoring tool, every gateway product — the REST tooling stack is mature and stable.
4. Versioning is straightforward.
Path versioning (/v2/), header versioning, or date-stamped versions all work cleanly. See the REST API versioning post for the strategies.
5. The shape your customers want often is REST.
A messaging API has messages. A billing API has invoices and customers. A weather API has stations and forecasts. Resources map well to REST. If your domain is a graph (a social network, a content management system with deeply interconnected nodes), GraphQL may be a better fit — but most product APIs aren't graphs.
Where GraphQL wins
1. Mobile / single-page apps with strict bandwidth budgets.
If your client needs to render a complex screen and you would otherwise make 6 REST calls to assemble it, GraphQL lets the client ask for exactly the fields it needs in one round trip. The classic Facebook mobile justification.
2. Heterogeneous internal consumers.
If five different teams inside a company consume the same API and they each want different subsets of the data, GraphQL lets each team write its own query. REST tends to push you toward "expand parameters" or many specific endpoints.
3. The schema is the API.
GraphQL's type system is its public contract. SDKs and tooling are generated from the schema. No separate OpenAPI document. For some teams this is simpler; for others (especially those who already have OpenAPI tooling) it's an additional thing to learn.
Where each one bites
REST gotchas
- N+1 round trips on rich list views. The fix is well-known (expand parameters, JSON:API includes, hand-written aggregate endpoints) but it's friction.
- Versioning discipline is a real ongoing cost. See the versioning post.
- Over-fetching: clients often get back fields they don't need.
GraphQL gotchas
- Caching is hard. HTTP-level caching is mostly off the table; you end up doing application-level caching with Apollo Cache, URQL, or Relay.
- Authorization at the field level is more complex than at the endpoint level. Every query has to be validated against per-field permissions.
- Query cost: untrusted clients can ship expensive queries. You need query-cost analysis, depth limits, or persisted-query enforcement.
- Tooling for SDK generation, docs hosting, and SEO is less mature than REST's. The same OpenAPI ecosystem isn't available.
- Server complexity tends to be higher.
What to pick, by team shape
- Public SaaS API, mixed customer base → REST + OpenAPI. The integration floor and tooling ecosystem are the deciding factors.
- Internal API behind your own UI, mobile-first → GraphQL is a real option, especially if the same team owns the client.
- Open-source library with an HTTP backend → REST. Lower friction for contributors.
- Existing REST API growing in complexity → don't migrate to GraphQL because it's trendy. Add expand parameters, sparse fieldsets, or JSON:API includes first. Migrate only when the round-trip cost is a clearly measured problem.
- Greenfield internal-tools API with one client → either is fine. Pick the one your team has more practice with.
How Bloom thinks about it
Bloom is a REST-first product. We generate OpenAPI 3.x specs into TypeScript and Python SDKs and host docs from the same source. We do not generate GraphQL SDKs today.
If your API is REST: Bloom is the workflow we built for you. Generate an SDK from your OpenAPI spec, preview the docs, ship.
If your API is GraphQL: Apollo and the URQL ecosystem are the standard stacks. Bloom is the wrong fit. We may revisit GraphQL support as the OpenAPI/GraphQL convergence work (e.g. openapi-to-graphql) matures.
The honest take
The REST vs GraphQL debate is mostly settled in practice. REST wins by default for product APIs because of HTTP caching, tooling maturity, and integration floor. GraphQL wins in specific shapes (mobile-first, internal multi-consumer, graph-native domains).
If you're choosing for a new public API and you can't articulate a specific reason GraphQL would help, pick REST. Add OpenAPI 3.1, generate SDKs, and ship.