In RESTful APIs, HTTP methods define the actions that can be performed on the resources (data entities) available on the server. Here's an overview of the most commonly used HTTP methods and how they are typically applied:
1. GET (Retrieve Data)
The GET method is used to request data from a server. It is a read-only operation, meaning it does not modify the data on the server. This is the most common method for retrieving information.
Usage: When you need to retrieve a resource or a collection of resources from a server.
Example:
Get a list of users:
GET /usersGet a specific user by ID:
GET /users/123
The GET method should be idempotent, meaning that calling it multiple times will always return the same result and not alter the server's state.
2. POST (Create Data)
The POST method is used to send data to the server to create a new resource. Unlike GET, which retrieves data, POST is used when a new entity is being added to the server.
Usage: To create a new resource on the server.
Example:
- Create a new user:
POST /userswith the body containing user information (e.g.,{"name": "John", "email": "john@example.com"}).
- Create a new user:
POST is not idempotent. Sending the same POST request multiple times could create duplicate resources.
3. PUT (Update or Replace Data)
The PUT method is used to update an existing resource or create a resource if it doesn't exist. It replaces the entire resource with the new data provided in the request body.
Usage: To update an existing resource. If the resource doesn't exist, it can create it (depending on the server's implementation).
Example:
- Update user data:
PUT /users/123with the body containing the updated user details (e.g.,{"name": "John", "email": "newemail@example.com"}).
- Update user data:
PUT requests are idempotent, meaning that sending the same PUT request multiple times will always produce the same result (the resource will be the same after each request).
4. DELETE (Remove Data)
The DELETE method is used to remove a resource from the server.
Usage: To delete a resource.
Example:
- Delete a specific user:
DELETE /users/123
- Delete a specific user:
DELETE requests are generally idempotent. Once a resource is deleted, sending the same DELETE request again will result in a 404 error because the resource no longer exists.
5. PATCH (Partial Update)
The PATCH method is used to apply partial modifications to an existing resource. Unlike PUT, which requires the full resource to be sent for an update, PATCH only requires the fields that need to be changed.
Usage: When you need to update only specific fields of a resource rather than the entire resource.
Example:
- Update a user's email:
PATCH /users/123with the body containing just the modified field (e.g.,{"email": "newemail@example.com"}).
- Update a user's email:
PATCH requests are not necessarily idempotent. Multiple PATCH requests might lead to different results, depending on the modifications made.
Differences Between PUT and PATCH:
PUT: Replaces the entire resource with the data in the request body. The full representation of the resource must be provided, and the server replaces the old resource with this new data.
PATCH: Modifies only the specified fields of the resource. It is intended for partial updates, meaning you don't need to send the full resource, just the changes.
Summary:
GET: Retrieve resource(s).
POST: Create new resource(s).
PUT: Replace or update resource(s).
DELETE: Remove resource(s).
PATCH: Apply partial update to a resource.
These methods define the basic interaction with RESTful APIs and are essential for designing RESTful services.