Clean APIs and Service Design

# CHAPTER 13

Clean APIs and Service Design #

1. Introduction #

2. Learning Objectives #

• Design clean, predictable, and resource-oriented REST APIs.

• Utilize standard HTTP Methods (GET, POST, PUT, DELETE) correctly.

• Abstract business logic away from Controllers into a dedicated Service Layer.

• Implement strict Request Validation to protect the backend.

• Standardize JSON Response structures for success and error states.

3. RESTful Naming Conventions #

• The Bad Way (Using Verbs in URLs):

• /getUsers

• /createNewUser

• /deleteUserById?id=5

• The Clean Way (Resource-Oriented):

• GET /users (Fetch all users)

• POST /users (Create a new user)

• GET /users/5 (Fetch user ID 5)

• DELETE /users/5 (Delete user ID 5)

4. The Service Layer (Thin Controllers) #

• The Problem: Developers write 500 lines of database queries, payment processing, and email sending directly inside the API Route Controller.

• The Clean Architecture: Controllers must be "Thin." The Controller's *only* job is to receive the HTTP Request, hand the data to a Service Class, and return the HTTP Response.

• The Service Layer: All business logic lives in a UserService or PaymentService. This allows you to call the same logic from an API, a CLI script, or a background job without duplicating code.

5. Request Validation (Fail Fast) #

• The Logic: If the API requires an email, and the client sends an empty string, the Controller should instantly return a 400 Bad Request error. Do not pass bad data into your database queries to see what happens.

• Data Transfer Objects (DTOs): In advanced systems, validated data is mapped into strongly-typed DTOs before being passed to the Service Layer, ensuring strict type safety.

6. Response Consistency #

• Standardized Success Structure:

{
  "status": "success",
  "data": { "id": 5, "name": "John" }
}

• Standardized Error Structure: Always use standard HTTP status codes (400, 401, 404, 500) and provide a consistent error format.

{
  "status": "error",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The email field is required."
  }
}

7. Diagrams/Visual Suggestions #

[ HTTP Request (POST /users) ]
          |
          v
[ Controller ] ---> 1. Validates Request (Returns 400 if invalid)
          |    ---> 2. Calls UserService->createUser()
          v
[ Service Layer ] ---> 1. Hashes Password
                  ---> 2. Calls Database Repository
                  ---> 3. Fires "UserCreated" Event (Email)
          |
          v
[ Controller ] ---> 3. Returns Standard JSON Response (201 Created)

8. Best Practices #

• Idempotency: A PUT or DELETE request should be idempotent. If a client sends DELETE /users/5 ten times in a row, the result on the server should be the exact same as sending it once (the user is deleted). It should not crash the server on the second attempt.

9. Common Mistakes #

• Ignoring HTTP Status Codes: A terrible API practice is returning a 200 OK status code, but having the JSON body say {"error": "User not found"}. This breaks standard web infrastructure. If the user is not found, the API must return a 404 Not Found HTTP status code.

10. Mini Project: Design a Clean REST API #

• POST /cart/additem

• POST /cart/removeitem?id=5

• GET /cart/getallitems

*Clean REST API Design:*

• POST /cart/items (Adds a new item to the cart)

• GET /cart/items (Retrieves all items in the cart)

• DELETE /cart/items/5 (Removes item ID 5 from the cart)

• PUT /cart/items/5 (Updates the quantity of item ID 5)

11. Practice Exercises #

1. 1. Explain why Controllers should be "Thin" and business logic should be abstracted into a "Service Layer."

1. 2. Provide a clean, standardized JSON structure for an API error response when a user submits an invalid password.

12. MCQs with Answers #

13. Interview Questions #

• Q: Explain the concept of standardizing API JSON responses. How does returning a consistent {"data": {}} envelope for success and an {"error": {}} envelope for failures impact frontend development speed?

• Q: "Never trust the client." Explain how Request Validation (failing fast at the Controller level) protects the underlying Service Layer from processing malicious or incomplete data.

• Q: What is Idempotency in the context of REST APIs? Why is the PUT method considered idempotent, while the POST method is not?

14. FAQs #

15. Summary #

16. Next Chapter Recommendation #