API Design and Communication Protocols

# CHAPTER 8

API Design and Communication Protocols #

1. Chapter Introduction #

2. REST (Representational State Transfer) #

The 4 Core HTTP Methods (CRUD):

• GET: Retrieve a resource. (Read)

• POST: Create a new resource. (Create)

• PUT / PATCH: Update an existing resource. (Update)

• DELETE: Remove a resource. (Delete)

*URL Design Best Practices:* URLs should be nouns, not verbs. *Bad:* POST /createNewUser *Good:* POST /api/v1/users (The POST method itself implies "create"). *Hierarchical Good:* GET /api/v1/users/123/orders/45 (Get order #45 for user #123).

3. The Tradeoffs of REST #

4. GraphQL (The Solution to Over-fetching) #

*Client Query:*

query {
  user(id: 123) {
    name
    posts(last: 3) { title }
  }
}

*Pros:* Perfect for mobile apps on slow networks (one request, exact data). *Cons:* Extremely difficult to cache via standard HTTP, complex backend implementation, risk of clients writing overly complex queries that crash the database.

5. gRPC (The King of Internal Communication) #

*Where to use it:* You rarely expose gRPC to external web browsers. You use gRPC for Server-to-Server internal communication within a Microservices architecture. It is roughly 7x-10x faster than REST.

6. WebSockets (Real-Time Communication) #

WebSockets create a persistent, bi-directional, full-duplex connection over a single TCP socket. The connection stays open indefinitely, allowing the Server to push a message to the Client the millisecond it happens. *Interview Use Cases:* WhatsApp, Multiplayer Gaming, Live Dashboards, Collaborative Editing (Google Docs).

7. API Gateways #

• Routing: Directs /users to the User Service and /billing to the Billing Service.

• Authentication: Validates the JWT token before letting the request into the internal network.

• Rate Limiting: Prevents a single IP from spamming the API (DDoS protection).

8. Real-World Scenario: Designing a Chat App API #

9. Mini Project: Whiteboard an API Spec #

1. 1. Fetching all to-dos.

1. 2. Creating a new to-do.

1. 3. Updating a to-do to "completed."

1. 4. Deleting a to-do.

10. Common Mistakes #

• Mixing Nouns and Verbs in REST: Writing endpoints like GET /deleteUser.

• Ignoring Pagination: Returning an array of 10,000 users in a single GET request will crash the client. Always design APIs with pagination (e.g., GET /users?limit=50&offset=100).

11. Best Practices #

• Versioning: Always include a version number in your API URLs (e.g., /api/v1/users). If you make a breaking change later, you can release /api/v2/users without breaking old mobile apps that haven't updated yet.

12. Exercises #

1. 1. If you are building a Microservice architecture and need the Billing Service to communicate with the User Service at maximum speed, which protocol should you use? (REST, GraphQL, or gRPC?)

1. 2. Why is GraphQL difficult to cache at the CDN/Load Balancer level compared to REST?

13. MCQs #

14. Interview Questions #

• Q: "Design the REST API for a ride-sharing app (like Uber). What endpoints do you need for a user to request a ride and cancel a ride?"

15. FAQs #

• Q: Do I need to know gRPC implementation details for an interview?

16. Summary #

17. Next Chapter Recommendation #