HTTP Methods: GET, POST, PUT, DELETE, and PATCH

In the world of RESTful API design, HTTP methods (often called "verbs") define the action we want to perform on a resource. If a resource is a "noun" (like a User or a Product), the HTTP method is the "verb" that tells the server what to do with that noun. Understanding these methods is crucial for building scalable, predictable, and standard-compliant web services.

The Role of HTTP Methods in REST

REST (Representational State Transfer) leverages the existing HTTP protocol. Instead of creating custom names for actions (like /getUser or /updateUser), we use standard HTTP methods applied to a resource URI (like GET /users/1). This makes APIs intuitive and easy to consume.

Before diving into each method, we must understand two key concepts: Safety and Idempotency.

• Safe Methods: These methods do not modify the state of the resource on the server. They are "read-only."
• Idempotent Methods: These methods can be called multiple times with the same result as a single call. The side effect on the server is the same regardless of how many times the request is made.

1. GET: Retrieving Resources

The GET method is used to request data from a specified resource. It is the most common method used in web development.

• Safe: Yes. It should never change the database state.
• Idempotent: Yes. Requesting the same data ten times should return the same data ten times (assuming no other processes changed it).

Example Request:

GET /api/v1/products/101

This request fetches the details of the product with ID 101.

2. POST: Creating Resources

The POST method is used to send data to the server to create a new resource. The server usually decides the ID of the new resource.

• Safe: No. It creates a new entry in the database.
• Idempotent: No. If you send the same POST request five times, you will likely create five identical records in your database.

Example Request:

POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}
    

3. PUT: Replacing Resources

The PUT method is used to update an existing resource or create it if it doesn't exist (though usually it is used for updates). PUT requires you to send the entire resource representation.

• Safe: No. It modifies the server state.
• Idempotent: Yes. If you update a user's name to "Jane" using PUT, calling it again with the same data won't change the outcome; the name remains "Jane."

Example Request:

PUT /api/v1/users/1
{
  "id": 1,
  "name": "Jane Doe",
  "email": "jane@example.com"
}
    

4. PATCH: Partial Updates

Unlike PUT, which replaces the whole resource, PATCH is used to apply partial modifications. Use this when you only want to update one or two fields of a large object.

• Safe: No.
• Idempotent: No (technically, though it can be implemented to be idempotent).

Example Request:

PATCH /api/v1/users/1
{
  "email": "new-email@example.com"
}
    

5. DELETE: Removing Resources

The DELETE method is used to remove a resource from the server.

• Safe: No.
• Idempotent: Yes. Once a resource is deleted, calling DELETE again will not change the fact that it is gone (even if the server returns a 404 the second time).

Method Mapping Flowchart

Here is a quick visual guide to how HTTP methods map to CRUD (Create, Read, Update, Delete) operations:

+--------+---------+------------+----------------+
| CRUD   | HTTP    | Idempotent | Safe           |
+--------+---------+------------+----------------+
| Create | POST    | No         | No             |
| Read   | GET     | Yes        | Yes            |
| Update | PUT     | Yes        | No             |
| Update | PATCH   | No         | No             |
| Delete | DELETE  | Yes        | No             |
+--------+---------+------------+----------------+
    

Common Mistakes

• Using GET for sensitive data: Never use GET to send passwords or API keys. GET parameters are visible in the URL and stored in browser history/server logs.
• Confusing PUT and PATCH: Developers often use PUT when they only intend to update a single field. This can lead to data loss if the client doesn't send the full object.
• Making GET requests non-safe: Never design an API where GET /delete-user?id=1 actually deletes a user. This violates the HTTP specification.
• Ignoring Idempotency: Failing to make PUT or DELETE idempotent can cause issues during network retries.

Real-World Use Cases

E-commerce Application

• GET /products: Browse the catalog.
• POST /cart: Add a new item to the shopping cart.
• PUT /cart/item/5: Change the quantity of item #5 to exactly 3.
• PATCH /user/profile: Update only the shipping address.
• DELETE /cart/item/5: Remove the item from the cart.

Interview Notes

• What is the difference between PUT and POST? POST is for creating resources where the server determines the URI. PUT is for replacing a resource at a known URI. POST is not idempotent; PUT is.
• Why is PATCH not always idempotent? If a PATCH request performs an operation like "increment": 1, calling it twice will increment the value twice, changing the result.
• What status code should a successful POST return? Usually 201 Created, often including a Location header pointing to the new resource.
• What is a "Safe" method? A method that only retrieves data and does not change the state of the server (e.g., GET, HEAD, OPTIONS).

Summary

Mastering HTTP methods is the foundation of RESTful API development. By using GET for retrieval, POST for creation, PUT for full updates, PATCH for partial updates, and DELETE for removal, you ensure your API is predictable and follows global standards. Always remember the rules of safety and idempotency to build robust systems that handle network failures and retries gracefully.

In the next lesson, Understanding HTTP Status Codes, we will explore how the server communicates the outcome of these requests back to the client.