Module 8 — APIs

REST, GraphQL, gRPC

Three main API paradigms. Different use cases, different trade-offs.

1The Restaurant Menu Analogy

💡 Simple Analogy

REST: Fixed menu. Order dish #5, you get exactly that dish.

GraphQL: Customizable order. "I want burger with no pickles, add bacon, side of fries."

gRPC: Professional kitchen. Chefs speak their own language, super efficient, but you need to understand the protocol.

2REST

REST (Representational State Transfer) uses HTTP verbs (GET, POST, PUT, DELETE) to operate on resources identified by URLs. Stateless, cacheable, widely adopted.

Example

GET /users/123 → Get user 123
POST /users → Create user
PUT /users/123 → Update user 123
DELETE /users/123 → Delete user 123

✓ Simple, well-understood

✓ Cacheable (HTTP caching)

✓ Great tooling

✗ Over-fetching / under-fetching

3GraphQL

GraphQL lets clients specify exactly what data they need. Single endpoint, query language for APIs. Developed by Facebook.

Example Query

query {
  user(id: 123) {
    name
    email
    posts(limit: 5) {
      title
    }
  }
}

✓ No over/under-fetching

✓ Typed schema

✓ Great for mobile (minimal data)

✗ Complex caching

✗ N+1 query problem

4gRPC

gRPC is a high-performance RPC framework using Protocol Buffers (binary serialization). Great for microservice-to-microservice communication. Developed by Google.

Example Proto Definition

service UserService {
  rpc GetUser(UserRequest) returns (User);
}
message UserRequest { int32 id = 1; }
message User { string name = 1; string email = 2; }

✓ Very fast (binary, HTTP/2)

✓ Strongly typed

✓ Bi-directional streaming

✗ Not browser-friendly

✗ Harder to debug (binary)

5Comparison

Aspect	REST	GraphQL	gRPC
Format	JSON	JSON	Protobuf (binary)
Protocol	HTTP/1.1	HTTP/1.1	HTTP/2
Best For	Public APIs	Mobile apps, varied clients	Internal microservices
Browser Support	Native	Native	Needs grpc-web

6Key Takeaways

1REST: simple, cacheable, great for public APIs. Industry standard.

2GraphQL: client specifies data needs. Great for mobile, multiple clients.

3gRPC: high performance, typed. Best for internal microservices.

4Most companies use REST for external, gRPC for internal.

5Choose based on use case, not hype. REST is often sufficient.

6In interviews: know trade-offs of each and when to use them.