Recap — Choosing Between REST, gRPC, GraphQL

# Choosing Between REST, gRPC, GraphQL Three dominant API styles in 2026. Each has clear strengths. Pick by use case, not by trend. ## REST (Representational State Transfer) The classic. Resources at URLs; HTTP verbs (GET, POST, PUT, DELETE). ``` GET /api/users # list users GET /api/users/123 # get user 123 POST /api/users # create user PUT /api/users/123 # update user DELETE /api/users/123 # delete user ``` Format: JSON usually; sometimes XML for legacy. ### When REST shines - Public APIs (developer-friendly, cacheable, easy to debug with curl). - Resource-oriented operations (CRUD on entities). - Wide tooling support (every language has REST clients). - HTTP caching (CDN-friendly, browser-friendly). ### REST trade-offs - Over/under-fetching (server returns fixed shape; clients get more or less than they need). - Multiple round trips for related data ("get user, then user's posts, then comments"). - No formal contract (OpenAPI/Swagger adds it, but optional). - Versioning is awkward (`/v1/users`, `/v2/users`). ## gRPC Google's RPC framework. Binary protocol (Protobuf), HTTP/2 transport. ```protobuf service UserService { rpc GetUser(GetUserRequest) returns (User); rpc CreateUser(CreateUserRequest) returns (User); } message User { int32 id = 1; string name = 2; } ``` ### When gRPC shines - Service-to-service communication (microservices). - Low-latency / high-throughput needs. - Strongly-typed contracts (Protobuf). - Streaming (bidirectional, server-streaming, client-streaming). - Multi-language (auto-generated clients in 11+ languages). ### gRPC trade-offs - Binary protocol — hard to debug without tooling (no `curl`). - Not browser-friendly (needs gRPC-Web proxy). - Less mature tooling than REST. - Protobuf compiles needed. ## GraphQL Query language for APIs. Client specifies exactly what data it wants. ```graphql query { user(id: "123") { name posts { title comments { body } } } } ``` Server resolves; returns exactly that shape. ### When GraphQL shines - Mobile/web clients with varying data needs. - Aggregating data from multiple services. - Avoiding over/under-fetching of REST. - Single endpoint (`/graphql`) for all queries. ### GraphQL trade-offs - Server-side complexity (resolver design, N+1 queries). - Caching is harder (each query is unique). - Authorization at field level (complex). - Learning curve for clients and servers. ## Comparison table | Aspect | REST | gRPC | GraphQL | |---|---|---|---| | Transport | HTTP/1.1 or 2 | HTTP/2 | HTTP/1.1 or 2 | | Format | JSON (usually) | Protobuf (binary) | JSON | | Schema | Optional (OpenAPI) | Required (proto) | Required (SDL) | | Streaming | Limited | Full bidirectional | Subscriptions | | Tooling | Mature | Growing | Maturing | | Mobile-friendly | OK | Good | Excellent | | Caching | Excellent | Limited | Hard | | Debugging | curl, browser | special tools | special tools | | Best for | Public APIs, CRUD | Microservices | Frontends | ## What to use when **REST**: - Public APIs you publish to third parties. - Resource-oriented operations. - Browser-served, cache-friendly endpoints. - When HTTP-level features (caching, status codes) help. **gRPC**: - Internal service-to-service. - Strict typing matters. - High throughput / low latency. - Multi-language polyglot teams. **GraphQL**: - Frontends fetching nested data. - Multiple data sources (BFF/aggregator pattern). - Mobile apps with bandwidth constraints. - Avoiding API fragmentation. Many production systems use all three: REST for public APIs, gRPC for internal services, GraphQL for the frontend BFF. ## Common to all: design considerations ### Pagination For lists: - **Offset pagination**: `?page=2&limit=20` — easy but breaks if data shifts. - **Cursor pagination**: `?cursor=abc123` — stable, scales better. - **Keyset pagination**: `?after_id=123` — for ordered lists. Cursor pagination is the modern default for APIs at scale. ### Versioning - **URL versioning**: `/v1/users`, `/v2/users` — most common. - **Header versioning**: `Accept: application/vnd.api+json;version=1`. - **No versioning, only additive changes**: works if you're strict. ### Authentication - **API keys**: simple; passed in header. For service-to-service. - **OAuth 2.0 / JWT**: standard for user-facing. - **mTLS**: certificate-based; high-security. ### Rate limiting Standard headers: ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 73 X-RateLimit-Reset: 1614556800 ``` 429 status when limit exceeded. ### Error responses Consistent shape: ```json { "error": { "code": "USER_NOT_FOUND", "message": "User 123 does not exist", "details": {...} } } ``` Use HTTP status codes meaningfully (404 for not found, 400 for bad request, 500 for server error). ## Common API design mistakes 1. **Inconsistent naming.** /getUser vs /users; pick one. 2. **No versioning strategy.** Breaking changes hit clients hard. 3. **Ve