GraphQL vs REST vs gRPC
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated=no, and tools listed (postman, graphql-playground) are manual inspection tools. The code_pattern signals (20+ endpoints returning large responses, mobile app using 10% of payload) are only apparent through architectural review or production monitoring — no automated tooling flags a wrong protocol choice.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix is a high-level guideline, not a one-line patch. Migrating between API protocols (REST→GraphQL or REST→gRPC) requires rewriting endpoint definitions, client integrations, authentication, caching strategies, and potentially BFF layers — touching every consumer of the API across the codebase. This is a systemic change, not a local one.
Closest to 'strong gravitational pull' (b7). The choice of API protocol shapes every future endpoint design, client contract, documentation, caching strategy, and tooling selection. Once a public REST API is established (or GraphQL schema is published), every new feature and every new client is shaped by that decision. The applies_to covers web and api contexts broadly, indicating wide reach.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field captures it precisely: developers assume GraphQL is universally better because it avoids over-fetching, but it introduces N+1 problems, complex caching, and operational overhead. Similarly, common_mistakes show gRPC misuse for browser APIs and GraphQL misuse for internal services. These are well-documented gotchas that experienced developers learn but intermediate developers regularly fall into.
Also Known As
TL;DR
Explanation
REST: resource-based (nouns in URLs), standard HTTP methods, cacheable with CDN, well understood — best for public APIs and simple CRUD. GraphQL: client specifies exact fields needed, single endpoint, eliminates over/under-fetching, but complex caching and N+1 risks — best for frontend-driven APIs with diverse client needs. gRPC: Protocol Buffers binary serialisation, HTTP/2, bidirectional streaming, strongly typed contracts, 5-10x faster than JSON REST — best for internal microservice communication where performance matters.
Common Misconception
Why It Matters
Common Mistakes
- GraphQL for internal service communication — gRPC is faster and better typed.
- REST for APIs with deeply variable client data needs — GraphQL handles this naturally.
- No DataLoader with GraphQL — N+1 problem makes GraphQL slower than REST without it.
- gRPC for browser-facing APIs — gRPC requires grpc-web proxy for browser clients.
Code Examples
// REST for mobile app — persistent over-fetching:
GET /api/users/42
// Returns: all 25 fields
// Mobile needs: name, avatar (2 fields)
// 23 fields wasted on every request// Right tool for the job:
// Public REST API — simple, cacheable, well-understood:
GET /api/products/42 → product data (CDN cacheable)
// GraphQL for mobile/web with varied needs:
query { user(id:42) { name avatar } } → exactly 2 fields
// gRPC for internal PHP microservices:
// payment.proto: rpc Charge(ChargeRequest) returns (ChargeResponse)
// Generated PHP client + binary protocol
// 5x faster than JSON REST for high-frequency calls