HTTP Methods and Status Codes

# CHAPTER 3

HTTP Methods and Status Codes #

1. Introduction #

2. Learning Objectives #

• Identify the four primary HTTP Methods used in REST APIs.

• Map HTTP Methods to database CRUD operations.

• Understand the 5 classes of HTTP Status Codes (1xx to 5xx).

• Select the appropriate Status Code for successful and failed API operations.

3. Beginner-Friendly Explanation #

• You want to read a file? You use GET.

• You want to add a brand new file? You use POST.

• You want to replace an existing file with a revised version? You use PUT.

• You want to destroy a file? You use DELETE.

When the cabinet responds, it flashes a light:

• Green Light (200s): "Success! I did what you asked."

• Yellow Light (400s): "You made a mistake. The file you asked for doesn't exist, or you lack the security clearance."

• Red Light (500s): "The filing cabinet is broken. It's my fault, not yours."

4. The Core HTTP Methods (The Verbs) #

1. 1. GET (Read): Retrieves data from the server.

• *Example:* GET /api/users (Fetch a list of users).

• *Rule:* GET requests must be Idempotent and Safe. They should *never* alter data in the database.

1. 2. POST (Create): Submits new data to the server to create a new resource.

• *Example:* POST /api/users (Create a new user account).

• *Rule:* POST is NOT idempotent. If you send the same POST request 3 times, you will create 3 identical users.

1. 3. PUT (Update/Replace): Replaces an entire existing resource with new data.

• *Example:* PUT /api/users/1 (Replace user #1's profile).

• *Rule:* PUT *is* idempotent. Sending the exact same update request 10 times results in the exact same database state as sending it once.

1. 4. DELETE (Delete): Removes a resource.

• *Example:* DELETE /api/users/1 (Delete user #1).

1. 5. *(Bonus)* PATCH (Partial Update): Updates only specific fields of a resource (e.g., just changing the email, leaving the rest untouched).

5. HTTP Status Codes (The Vocabulary) #

• 1xx (Informational): Rarely used in standard REST APIs.

• 2xx (Success): Everything worked perfectly.

• 3xx (Redirection): The resource moved; go look over there.

• 4xx (Client Error): The Client (Frontend) messed up.

• 5xx (Server Error): The Server (Backend) crashed.

6. The Most Important Codes to Memorize #

The Successes (200s)

• 200 OK: Standard success for GET and PUT.

• 201 Created: Specific success for POST. "I successfully created the database record."

• 204 No Content: Success for DELETE. "I deleted it, and I have no data to send back to you."

The Client Errors (400s) - Your Fault

• 400 Bad Request: You sent invalid JSON or missing fields.

• 401 Unauthorized: You are not logged in. (Missing or invalid token).

• 403 Forbidden: You are logged in, but you don't have Admin permissions to do this.

• 404 Not Found: The URL or Resource ID does not exist.

The Server Errors (500s) - My Fault

• 500 Internal Server Error: My database crashed or my code threw an exception.

7. Real-World API Examples #

// 1. Fetching data
GET /api/articles/42
Response: 200 OK
{ "id": 42, "title": "Learn REST" }

// 2. Creating data
POST /api/articles
Body: { "title": "New Post" }
Response: 201 Created

// 3. Client makes a mistake
DELETE /api/articles/99999
Response: 404 Not Found
{ "error": "Article does not exist." }

8. Implementation Examples (Express & Laravel) #

Express.js (Node)

// Only responds to GET requests
app.get('/api/users', (req, res) => {
    res.status(200).json(users);
});

// Only responds to POST requests
app.post('/api/users', (req, res) => {
    // Logic to save user...
    res.status(201).json({ message: "User created" });
});

Laravel (PHP)

// Only responds to GET requests
Route::get('/users', [UserController::class, 'index']);

// Only responds to DELETE requests
Route::delete('/users/{id}', [UserController::class, 'destroy']);

9. Best Practices #

• Never Return 200 for Errors: A massive anti-pattern is an API that crashes, but the server returns HTTP 200 OK with a JSON body saying { "status": "error" }. This breaks frontend networking libraries (like Axios or Fetch) which rely on the 3-digit HTTP code to trigger .catch() blocks. If there is an error, return a 4xx or 5xx code!

10. Common Mistakes #

• Using GET to Delete or Create: You should never design a URL like GET /api/users/delete/5. Because browsers pre-fetch GET requests to speed up loading, a browser might accidentally navigate to that URL in the background, deleting your database records unintentionally! GET must remain strictly read-only.

11. Exercises #

1. 1. Map the four primary HTTP Methods (GET, POST, PUT, DELETE) to the four database CRUD operations (Create, Read, Update, Delete).

12. Coding Challenges #

• Challenge: You are designing an API endpoint that allows a user to update their email address. They submit an email that is already taken by another user. Which specific 4xx Status Code should your API return to indicate the Client made a bad request?

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the concept of "Idempotency" in REST APIs. Which HTTP Methods are idempotent, and which are not?

• Q: Walk me through the difference between a 401 Unauthorized and a 403 Forbidden status code. Provide a concrete example of when an API should return each.

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #