What is the difference between PUT, POST and PATCH?

PUT, POST, and PATCH are methods in the HTTP protocol, primarily used for data submission and updates. Although these methods share some similarities, they have distinct differences in usage scenarios and behavior. I will elaborate on the characteristics and usage scenarios of each method.

1. POST

POST method is one of the most commonly used methods in the HTTP protocol, primarily for creating new resources.

• Usage scenarios: When you need to create a new record on the server, you typically use the POST method. For example, if you are creating a new user account, you might send a POST request to the server containing the user's information.
• Characteristics: POST requests can be used not only for creating resources but also for triggering other non-idempotent operations, such as sending emails.

Example: Assume we have an API endpoint for user registration /api/users. You can send a POST request to this endpoint containing user data, such as:

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

{
  "username": "newuser",
  "email": "newuser@example.com"
}

This request creates a new user record on the server.

2. PUT

PUT method is primarily used for updating existing resources or creating a specific resource when it does not exist.

• Usage scenarios: If you know the exact location of the resource and need to update or replace it, you should use the PUT method. For example, updating a user's complete information.
• Characteristics: PUT is idempotent, meaning that executing the same PUT request multiple times results in the same outcome.

Example: Assume we need to update the information for user ID 123, we can send the following PUT request:

http
PUT /api/users/123
Content-Type: application/json

{
  "username": "updateduser",
  "email": "updateduser@example.com"
}

This request replaces all information for user ID 123.

3. PATCH

PATCH method is used for partially modifying resources.

• Usage scenarios: When you only need to update part of the resource information rather than the entire resource, using the PATCH method is more appropriate and efficient.
• Characteristics: PATCH is also idempotent; theoretically, executing the same PATCH request multiple times results in the same final state of the resource.

Example: Continuing with the user example, if we only need to update the user's email address, we can send a PATCH request:

http
PATCH /api/users/123
Content-Type: application/json

{
  "email": "newemail@example.com"
}

This request updates only the email address field for user ID 123 without affecting other data.

Summary

• POST is used for creating new resources.
• PUT is used for replacing existing resources or creating a specific resource when it does not exist.
• PATCH is used for modifying parts of resources.

Choosing the appropriate method not only improves the semantic clarity of the API but also helps ensure the performance and efficiency of the application.