HTTP Methods — Best Practices Guide

As Wikipedia’s definition of REST says, REST is the architecture used to design and development of WWW (World Wide Web)[1]. REST is used to create stateless, reliable web-based applications.

Image Credit: IETF HTTP Working Group (HTTPbis)

HTTP methods are used for action to be performed on the identified resource. The following are most 5 used methods in common HTTP-based architecture.

1. Get — The GET method requests that the target resource transfer a representation of its state.
2. Post — The POST method requests that the target resource process the representation.
3. Patch — The PATCH method requests that the target resource modify its state.
4. Put — The PUT method requests that the target resource create or update its state.
5. Delete — The DELETE method requests that the target resource delete its state.

Get Method

1. Resource Retrieval: The GET method is used to retrieve information about a resource or a collection of resources from the server. It is a safe and idempotent operation, meaning it should not modify the state of the server and can be repeated multiple times without changing the server’s state.
2. URL Endpoint: The URL to which the GET request is sent should represent the specific resource or collection of resources being requested. For example, if you’re retrieving information about a user with ID 123, the URL might be /users/123.
3. Query Parameters: GET requests can include query parameters in the URL to specify additional criteria for filtering, sorting, or paginating the requested resources. These parameters are typically appended to the URL after a question mark (?) and separated by ampersands (&). For example, /users?status=active&limit=10.
4. Response Body: In addition to the status code, the server includes a response body containing the requested data, if applicable. The response body is typically in a format such as JSON or XML and contains the attributes of the requested resource(s).
5. Response Codes: After processing the GET request, the server should respond with an appropriate HTTP status code to indicate the outcome of the request. Common status codes for GET requests include:

• 200 OK: This status code indicates that the request was successful, and the server is returning the requested data in the response body.
• 404 Not Found: If the requested resource does not exist, the server should respond with a 404 status code to indicate that the resource was not found.
• 401 Unauthorized: If the client is not authenticated and the requested resource requires authentication, the server should respond with a 401 status code.
• 403 Forbidden: If the client does not have permission to access the requested resource, the server should respond with a 403 status code.

POST Method

1. Resource Creation: POST requests are used to create a new resource on the server. The client sends data in the request payload, and the server processes this data to create the new resource.
2. Payload: The payload of a POST request typically contains the data necessary to create the resource. This data is usually in a format such as JSON or XML. The payload should include all the required information for creating the resource, such as attribute values.
3. URL Endpoint: The URL to which the POST request is sent should typically represent the collection or type of resource being created, rather than a specific instance of that resource. For example, if you’re creating a new user, the URL might be /users.
4. Response Body: In addition to the status code, the server may include a response body with more details about the outcome of the request. This could include information about the newly created resource or any errors encountered during processing.
5. Response Codes: After processing the POST request, the server should respond with an appropriate HTTP status code to indicate the outcome of the request. Common status codes for POST requests include:

• 201 Created: This status code indicates that the request was successful, and a new resource has been created. The response should include a Location header specifying the URL of the newly created resource.
• 400 Bad Request: If the request payload is malformed or missing required data, the server should respond with a 400 status code to indicate a bad request.
• 401 Unauthorized: If the client is not authenticated and the resource creation requires authentication, the server should respond with a 401 status code.
• 403 Forbidden: If the client does not have permission to create the resource, the server should respond with a 403 status code.
• 422 Unprocessable Entity: If the server understands the request payload but cannot process it due to semantic errors (e.g., invalid data format), it should respond with a 422 status code.

PATCH Method

1. Partial Update: The PATCH method is used to apply partial modifications to a resource. Unlike PUT, which requires sending the complete representation of the resource, PATCH only sends the attributes that are intended to be updated.
2. Payload: The payload of a PATCH request contains only the attributes that need to be modified or updated.
3. URL Endpoint: Similar to PUT, the URL should represent the specific resource being updated.
4. Response Codes: After processing the PATCH request, the server should respond with an appropriate HTTP status code to indicate the outcome of the request. Common status codes for PATCH requests include:

• 200 OK or 204 No Content: If the partial update is successful, the server should respond with a 200 status code if returning a response body with the updated resource, or 204 if not returning a response body.

PUT Method

1. Resource Replacement: The PUT method is used to update or replace an existing resource or create a new resource if it does not exist at the specified URL.
2. Payload: The payload of a PUT request contains the complete representation of the resource being updated or replaced. It should include all the attributes of the resource, even if some attributes remain unchanged.
3. URL Endpoint: The URL to which the PUT request is sent should represent the specific resource being updated or replaced. For example, /users/123 to update user with ID 123.
4. Response Codes: After processing the PUT request, the server should respond with an appropriate HTTP status code to indicate the outcome of the request. Common status codes for PUT requests include:

• 200 OK or 204 No Content: If the update or replacement is successful, the server should respond with a 200 status code if returning a response body with the updated resource, or 204 if not returning a response body.
• 201 Created: If a new resource is created due to the PUT request, the server should respond with a 201 status code.

DELETE Method

1. Resource Deletion: The DELETE method is used to remove a resource from the server.
2. URL Endpoint: The URL should represent the specific resource to be deleted.
3. Response Codes: After processing the DELETE request, the server should respond with an appropriate HTTP status code to indicate the outcome of the request. Common status codes for DELETE requests include:

• 200 OK or 204 No Content: If the deletion is successful, the server should respond with a 200 status code if returning a response body with details about the deleted resource, or 204 if not returning a response body.
• 404 Not Found: If the requested resource does not exist, the server should respond with a 404 status code.

By following these rules, clients can effectively retrieve information from RESTful APIs using the specified REST methods, and servers can provide clear and meaningful responses to these requests.