Architectural Styles
REST, GraphQL, gRPC, and the honest comparison every API designer needs to make.
Three styles dominate modern API design. REST is the default — resources, verbs, statelessness, cache-friendly. GraphQL gives the client query power at the cost of server complexity and a new N+1 problem. gRPC is the polyglot RPC framework Google open-sourced; service-definition-first with code-generated clients in every language.
This topic walks each style on its own terms and finishes with a head-to-head comparison. The right answer depends on your client, your team, and your latency budget — there is no universal winner.
Key concepts
- REST is six constraints in a trench coat — uniform interface, statelessness, cacheable, client-server, layered, code-on-demand (optional)
- RESTful API design is mostly about path conventions, status codes, and pagination
- GraphQL trades server-side complexity for client-side query flexibility
- gRPC is the strongly-typed, polyglot RPC story; Protobuf + HTTP/2 streaming
- No style is universally correct — the comparison must be honest about each one's weak spot
Reference template
// Picking an architectural style
1. Polyglot internal traffic with strict types? → gRPC
2. Mobile / web client with diverse fetch needs? → GraphQL
3. Public partner API, browser-friendly? → REST
4. Real-time bidirectional? → WebSocket (not on this list, but worth naming)
5. All three above co-exist in real systems — pick the right one per surface, not per companyAdapt to your problem; the structure is the load-bearing part.
Common pitfalls
- Treating GraphQL as 'better REST' — it has its own N+1, caching, and authorisation issues
- Building a gRPC service for a browser-only client without grpc-web
- REST without HATEOAS in the room every quarter; you'll lose the philosophical debate, just move on
- Picking the style before you know the client
Related topics
Items (6)
- Web API Architectural Styles — Overview
REST, GraphQL, gRPC, SOAP, WebSocket, webhook. The catalogue, when each is right, and why every team thinks theirs is special.
Concept Foundational - REST — The Architectural Style
Resources, verbs, statelessness, cache, uniform interface, HATEOAS. Fielding's PhD thesis applied to your CRUD endpoints.
Building Block Foundational - RESTful API Design in Practice
Path conventions, status codes that fit, payload shape, pagination, filtering, the bulk-operations friction every REST API hits.
Building Block Foundational - GraphQL — A Query Language for APIs
One endpoint, client-shaped responses, the N+1 problem, schema as the contract. When the flexibility earns its complexity.
Building Block Intermediate - gRPC — Protobuf over HTTP/2
Service-definition-first, code-generated clients, streaming variants, the polyglot internal-RPC story that won at Google.
Building Block Intermediate - REST vs GraphQL vs gRPC — Comparison
The honest trade-offs. Latency, payload size, tooling, debuggability, mobile-friendliness, where each one breaks first.
Concept Intermediate