API Design (REST/GraphQL/gRPC)
Overview
REST, GraphQL, and gRPC are three styles for designing APIs between clients and services. REST models resources over HTTP, GraphQL lets clients query exactly the fields they need through a single endpoint, and gRPC is a contract-first, binary remote-procedure-call framework built for fast service-to-service communication.
Key Concepts
- REST exposes resources (nouns like
/users/123) manipulated with HTTP verbs. It is stateless, leans on HTTP status codes and caching, and is universally supported, but its fixed response shape causes over-fetching (returning more fields than needed) or under-fetching (needing extra round trips). - GraphQL exposes a single endpoint backed by a typed schema. Clients send a query describing exactly the fields they want, which eliminates over- and under-fetching and shines when many client types need different slices of the same data. The costs are harder HTTP caching, potentially expensive nested queries, and the N+1 fetching problem on the server.
- gRPC is a contract-first framework that sends Protocol Buffers (a compact binary format) over HTTP/2. Its binary payloads and multiplexed streams make it fast and well-suited to service-to-service calls and bidirectional streaming, but it is not natively callable from browsers and its binary format is less human-readable.
These styles are not mutually exclusive: an API gateway often exposes REST or GraphQL at the edge and translates to gRPC internally.
Comparison of API Styles
| Dimension | REST | GraphQL | gRPC |
|---|---|---|---|
| Data format | Usually JSON | JSON | Binary (Protocol Buffers) |
| Transport | HTTP/1.1 or HTTP/2 | HTTP (single endpoint) | HTTP/2 |
| Fetching | Fixed responses; over/under-fetch | Client picks exact fields | Fixed, contract-defined |
| Contract | OpenAPI (optional) | Schema (required) | .proto (required) |
| Streaming | Limited | Subscriptions | First-class bidirectional |
| Browser support | Native | Native | Needs a proxy (grpc-web) |
| Caching | Easy via HTTP caching | Harder (single POST endpoint) | Manual |
| Best fit | Public CRUD APIs | Aggregating varied client needs | Internal service-to-service |
Trade-offs
Choose REST for public-facing CRUD APIs that need broad client compatibility and HTTP caching. Choose GraphQL when many clients want different data shapes (mobile versus web) or when one query must aggregate several backends without proliferating endpoints. Choose gRPC for low-latency, high-throughput internal calls and streaming between services, especially in a polyglot fleet that benefits from strong generated contracts.
Interview Tips
- State the caller first, then pick the style: REST for public CRUD and cacheable reads, GraphQL when diverse clients need tailored payloads, gRPC for internal high-performance calls.
- Mention that you can mix them behind a gateway.
- Avoid claiming one is universally best - the interviewer is testing fit, not fandom.
Summary
- REST models resources over HTTP and is the default for public, cacheable CRUD APIs.
- GraphQL lets clients request exact fields from one endpoint, solving over- and under-fetching for diverse clients.
- gRPC is a fast, contract-first binary RPC framework ideal for internal service-to-service and streaming.
- Caching is easiest in REST and hardest in GraphQL; gRPC is not browser-native without a proxy.
- Match the style to the caller, and combine them behind a gateway when it helps.