APIs and Communication

# CHAPTER 7

APIs and Communication #

1. Introduction #

2. Learning Objectives #

• Define what an API is in the context of distributed systems.

• Architect clean, resource-based RESTful APIs using standard HTTP verbs.

• Compare REST architecture against the dynamic querying of GraphQL.

• Explain the role of an API Gateway in microservices architecture.

• Engineer defensive mechanisms like Rate Limiting and Pagination.

3. The REST Architectural Style #

• Resource-Based: In REST, everything is a "Resource" (e.g., Users, Posts, Products). You do not design URLs based on *actions* (like /getRecentPosts); you design URLs based on *nouns* (like /posts).

• Standardized Verbs: You manipulate the resources using strict HTTP verbs:

• GET /users (Retrieve a list of users)

• POST /users (Create a new user)

• GET /users/123 (Retrieve a specific user)

• PUT /users/123 (Update a specific user)

• DELETE /users/123 (Delete a specific user)

• JSON Standard: The vast majority of REST APIs send and receive data formatted as JSON (JavaScript Object Notation).

4. GraphQL (The REST Alternative) #

• The REST Flaw: If a mobile app only needs a user's name to display in a top bar, a REST call to GET /users/123 might return 50 fields of data (email, address, history), wasting the user's mobile data bandwidth (Over-fetching).

• The GraphQL Solution: Developed by Facebook, GraphQL is a query language. There is only ONE endpoint (/graphql). The client explicitly requests *exactly* the data it wants.

• The Query: The client sends: query { user(id: 123) { name } }

• The Response: The server returns exactly one field: { "data": { "user": { "name": "John" } } }. Highly efficient, but significantly more complex to engineer on the backend.

5. The API Gateway #

• The Gateway Pattern: An API Gateway is a specialized server that sits at the absolute front of your architecture (often combined with the Load Balancer).

• The Router: The mobile app only talks to ONE URL (the API Gateway). If the app requests /payments, the Gateway routes it to the Payment Microservice. If it requests /users, the Gateway routes it to the User Microservice.

• The Shield: The API Gateway handles Authentication, SSL Termination, and Logging centrally, so your 50 microservices don't have to duplicate that code.

6. Rate Limiting (Defensive Design) #

• The Attack: A malicious bot or a buggy client script tries to hit your POST /login API 10,000 times a second, attempting to crash your database or brute-force a password.

• The Defense: Rate Limiting.

• The Logic: You configure the API Gateway to track IP addresses or API Keys. You implement a rule: "Maximum 100 requests per minute per IP." If they exceed the limit, the Gateway blocks them and returns an HTTP 429 Too Many Requests status code, completely shielding the fragile backend servers.

7. Diagrams/Visual Suggestions #

[ Mobile App ] --(HTTPS)--> [ API GATEWAY (Rate Limiting & Auth) ]
                                |
                                |-- (Route /users) --> [ User Microservice ]
                                |
                                |-- (Route /pay) ----> [ Billing Microservice ]
                                |
                                |-- (Route /search) -> [ Search Microservice ]

8. Best Practices #

• Pagination: Never return an unpaginated list from an API. If a client calls GET /users, and you have 10 million users in your database, your server will try to load 10 million records into RAM, instantly crashing the server. *Always* enforce pagination by default: GET /users?limit=50&page=1.

9. Common Mistakes #

• Breaking Changes: A startup alters the data structure of their GET /products API. *The Failure:* The old version of their iOS app (which millions of users still have installed and haven't updated) expects the old structure. The entire app breaks for millions of users instantly. *The Fix:* API Versioning. Always prefix your APIs: GET /v1/products. If you need to make a breaking change, launch GET /v2/products and leave v1 running for legacy apps.

10. Mini Project: Design APIs for a Social App #

1. 1. The Users:

• Create account: POST /v1/users

• Get my profile: GET /v1/users/me

1. 2. The Tweets (Resources):

• Post a tweet: POST /v1/tweets

• Get latest feed: GET /v1/tweets?sort=latest&limit=20

• Delete a tweet: DELETE /v1/tweets/987

1. 3. The Likes (Sub-resources):

• Like a tweet: POST /v1/tweets/987/likes

11. Practice Exercises #

1. 1. Define the core principles of a RESTful API. Explain why designing APIs around "Resources" (nouns) instead of "Actions" (verbs) creates a more scalable architecture.

1. 2. Compare REST to GraphQL. In a mobile environment with poor network connectivity, why might a mobile engineer heavily advocate for replacing REST with GraphQL?

12. MCQs with Answers #

13. Interview Questions #

• Q: Explain the catastrophic danger of not implementing Pagination on a REST API endpoint that retrieves a list of resources. Walk me through the exact failure cascade from the Database to the Server RAM.

• Q: A mobile application crashes globally because the backend team changed a field name in the JSON response payload. How does the architectural practice of "API Versioning" completely prevent this disaster?

• Q: Compare and contrast the architecture of REST vs. GraphQL. If you are building a massive public API for third-party developers (like Stripe or GitHub), which architecture is generally preferred and why?

14. FAQs #

15. Summary #

16. Next Chapter Recommendation #