When designing a new API or evaluating an existing one, you will encounter three dominant paradigms: REST, GraphQL, and gRPC. They make different trade-offs, and choosing the wrong one creates friction throughout a project’s lifecycle. Here is how to choose.
REST (Representational State Transfer)
REST is the default API paradigm for most web applications. It uses HTTP methods (GET, POST, PUT, PATCH, DELETE) to operate on resources identified by URLs. Characteristics: stateless; resource-oriented; widely understood; excellent tooling and client support across every language. Strengths: simplicity and universality — any HTTP client can consume a REST API; excellent caching via HTTP; well-understood patterns (CRUD on resources); easier to implement and debug than alternatives; works naturally with web browsers. Weaknesses: over-fetching (a single endpoint returns all fields even if the client only needs two); under-fetching (the client needs multiple round trips to assemble data from multiple resources — the N+1 problem); versioning is painful (v1, v2, v3 in URLs, or Accept-Version headers); no built-in contract definition (though OpenAPI/Swagger fills this gap). When to use REST: public APIs consumed by many clients (different platforms, languages, third parties); simple CRUD applications; cases where HTTP caching is valuable; teams that prioritise broad tooling support and ease of onboarding; microservices communicating with external clients.
GraphQL
GraphQL is a query language and runtime developed by Facebook (2015). Instead of multiple endpoints each returning fixed shapes, GraphQL has a single endpoint through which clients specify exactly the data they need. Strengths: solves over-fetching (clients request only the fields they need); solves under-fetching (a single query can retrieve nested data from multiple types); strongly typed schema serves as contract and documentation; excellent for rapid iteration on frontends without backend changes; real-time subscriptions built in. Weaknesses: complexity — implementing a GraphQL server is harder than REST; N+1 query problem moves to the server (the DataLoader pattern solves this, but requires explicit implementation); HTTP caching doesn’t work naturally with POST-based queries; difficult to test and debug without specific tooling (GraphiQL, Altair); not well-suited for binary or streaming data. When to use GraphQL: frontend-driven APIs where multiple clients (web, iOS, Android) have different data needs; data graph products where entities have complex relationships; teams with dedicated API infrastructure that can absorb the implementation complexity; APIs where rapid frontend iteration is a priority; cases where a typed schema contract provides significant value.
gRPC
gRPC is Google’s high-performance RPC framework (2016). It uses Protocol Buffers (protobuf) as the interface definition language and HTTP/2 as the transport. Characteristics: strongly typed contracts via .proto files; supports unary, server-streaming, client-streaming, and bidirectional streaming; generates client and server code in multiple languages from the .proto definition. Strengths: performance — protobuf binary serialisation is 3–10x smaller than JSON; HTTP/2 multiplexing reduces latency; first-class streaming support; strongly typed contracts enforced at compile time; excellent for polyglot environments (generate clients in Go, Python, Java, Rust from one .proto file). Weaknesses: not human-readable (binary protocol requires tooling to inspect); poor browser support (grpc-web is a workaround, but indirect); steeper learning curve; requires proto file distribution and versioning discipline. When to use gRPC: internal microservice-to-microservice communication where performance is important; streaming use cases (real-time data, event streaming); polyglot environments where multiple languages share a contract; latency-sensitive applications; cases where compile-time type safety across service boundaries is valuable. Summary rule of thumb: public API → REST; frontend data layer → GraphQL; internal services → gRPC.
