APIs: REST, GraphQL & gRPC
Master REST design principles, compare REST vs GraphQL vs gRPC with real trade-offs, learn API versioning, pagination strategies, and idempotency — essential for designing scalable system interfaces.
Master REST design principles, compare REST vs GraphQL vs gRPC with real trade-offs, learn API versioning, pagination strategies, and idempotency — essential for designing scalable system interfaces. This hands-on tutorial focuses on practical implementation of apis: rest, graphql & grpc concepts.
APIs: REST, GraphQL & gRPC
The API is the contract between your system's components — between your frontend and backend, and between your microservices. A well-designed API is easy to use, hard to misuse, and scalable. A poorly designed one will haunt you for years.
REST: The Dominant Paradigm
REST (Representational State Transfer) is an architectural style, not a protocol. It uses HTTP methods to perform operations on resources (nouns, not verbs).
REST Design Principles
REST vs GraphQL vs gRPC — The Trade-Off Table
| Feature | REST | GraphQL | gRPC |
|---|---|---|---|
| Protocol | HTTP/1.1 or HTTP/2 | HTTP/1.1 or HTTP/2 | HTTP/2 (required) |
| Data Format | JSON (human-readable) | JSON (human-readable) | Protocol Buffers (binary, compact) |
| Over/Under-fetching | ⚠️ Over-fetching common | ✅ Exactly what you ask for | Defined by schema |
| Performance | Good | Can be slower (complex queries) | Very fast (binary + HTTP/2) |
| Streaming | ❌ Limited | ⚠️ Subscriptions only | ✅ Bidirectional streaming |
| Browser Support | ✅ Native | ✅ Native | ⚠️ Needs grpc-web proxy |
| Best For | Public APIs, simple CRUD | Mobile apps, complex data needs | Internal microservices, high performance |
| Used By | Twitter, GitHub, Stripe | GitHub (v4), Shopify, Meta | Google, Netflix, Square |
Pagination Strategies
Never return unbounded lists. At scale, GET /users returning 50 million records will crash your system. Always paginate.
Idempotency — Critical for Reliability
An API is idempotent if calling it multiple times produces the same result as calling it once. This is essential for retries.
[!IMPORTANT] Network failures are inevitable. If your POST /payments endpoint is NOT idempotent and a client retries on timeout, the user gets charged twice. Stripe, Braintree, and every payment API use idempotency keys to prevent this.
Quiz
Quiz
Question 1 of 3Which HTTP method is both safe AND idempotent?
REST vs GraphQL vs gRPC — Quick Comparison
| Feature | REST | GraphQL | gRPC |
|---|---|---|---|
| Protocol | HTTP/1.1 | HTTP/1.1+ | HTTP/2 |
| Data Format | JSON/XML | JSON | Protobuf (binary) |
| Flexibility | Fixed endpoints | Client-defined queries | Strict schema (proto) |
| Performance | Good | Good | Excellent |
| Over-fetching | Common | Eliminated | N/A (typed) |
| Browser Support | Native | Native | Needs proxy (Envoy) |
| Use Case | Public APIs | Complex frontends | Internal microservices |
| Caching | HTTP cache (easy) | Harder | Via interceptors |
Official Resources
- REST API Design — Roy Fielding's Dissertation
- GraphQL Official Documentation
- gRPC Official Documentation
- API Design Patterns — Google AIP
Key Takeaways
✅ REST uses HTTP methods on nouns (resources) — use it for public APIs and simple CRUD.
✅ GraphQL solves over/under-fetching — ideal for complex mobile apps with diverse data needs.
✅ gRPC is binary + HTTP/2 — ideal for internal microservices where performance is critical.
✅ Always paginate — use cursor-based for feeds, offset for admin tables.
✅ Idempotency keys are essential for payment, order, and any create operations that must be retry-safe.
What's Next?
Next Module: Scalability & Performance — Load Balancing, Caching, and CDNs.