HTTP Methods

1. Introduction

HTTP methods are the backbone of REST APIs, providing the set of operations that clients can perform on resources. Each method has a specific purpose and defines the action to be taken on a given resource, such as retrieving data, creating new entries, updating existing records, or deleting resources. Understanding these methods is crucial for designing a well-structured and intuitive REST API. This chapter explores the core HTTP methods—GET, POST, PUT, PATCH, DELETE, and others—detailing their usage, best practices, and how they map to CRUD operations.

2. Core HTTP Methods

1. GET (Retrieve Data)

   • Purpose: The GET method is used to retrieve data from a server. It requests a representation of a specified resource and should never modify data on the server.

   • Idempotency: GET requests are idempotent, meaning multiple identical requests have the same effect as a single request. This property ensures that GET requests can be safely repeated without changing the server’s state.

   • Use Cases:

     • Fetching a list of users: GET /users
     • Retrieving a specific user’s details: GET /users/123

   • Response Codes:

     • 200 OK: Successfully retrieved the resource.
     • 404 Not Found: The requested resource does not exist.

2. POST (Create Resource)

   • Purpose: The POST method is used to create a new resource on the server. Unlike GET, POST requests may change the state of the server by adding new data.

   • Non-Idempotency: POST requests are non-idempotent, meaning repeated requests will create multiple instances of the resource, making it crucial to handle them carefully to avoid duplication.

   • Use Cases:

     • Creating a new user: POST /users
     • Adding a new product to a catalog: POST /products

   • Response Codes:

     • 201 Created: Resource has been successfully created.
     • 400 Bad Request: Invalid input or malformed request data.

3. PUT (Update Resource)

   • Purpose: The PUT method is used to update an existing resource or create a resource if it does not exist. It sends a complete representation of the resource, replacing all the current data with the request data.

   • Idempotency: PUT requests are idempotent; making the same request multiple times results in the same outcome, as the resource’s state is consistently updated to match the request.

   • Use Cases:

     • Updating user information: PUT /users/123
     • Replacing an entire product listing: PUT /products/456

   • Response Codes:

     • 200 OK: Resource successfully updated.
     • 201 Created: Resource created if it did not exist.
     • 204 No Content: Update successful, no content returned.

4. PATCH (Partial Update)

   • Purpose: The PATCH method is used to apply partial updates to an existing resource. Unlike PUT, PATCH only modifies the specified fields, rather than replacing the entire resource.

   • Idempotency: PATCH requests are generally idempotent; repeating the same request will consistently update the resource to the desired state.

   • Use Cases:

     • Updating only a user’s email address: PATCH /users/123
     • Changing the price of a product: PATCH /products/456

   • Response Codes:

     • 200 OK: Resource successfully updated.
     • 204 No Content: Update successful, no content returned.
     • 400 Bad Request: Invalid data provided.

5. DELETE (Remove Resource)

   • Purpose: The DELETE method is used to remove a specified resource from the server. It performs a destructive operation, permanently deleting data.

   • Idempotency: DELETE requests are idempotent; sending the same request multiple times will result in the same state—either the resource is deleted, or it is already absent.

   • Use Cases:

     • Deleting a user account: DELETE /users/123
     • Removing a product from a catalog: DELETE /products/456

   • Response Codes:

     • 200 OK: Resource successfully deleted (sometimes used, but not always standard).
     • 204 No Content: Resource deleted, no additional information provided.
     • 404 Not Found: Resource does not exist.

3. Additional HTTP Methods

1. HEAD (Retrieve Headers)

   • Purpose: The HEAD method is similar to GET, but it retrieves only the headers of the response, not the body. It is useful for checking resource metadata without transferring large amounts of data.

   • Use Cases:

     • Checking if a resource exists before making a GET request: HEAD /users/123

   • Response Codes:

     • Mirrors GET response codes but without the response body.

2. OPTIONS (Query Supported Methods)

   • Purpose: The OPTIONS method is used to query the server for the supported HTTP methods on a specified resource. It is commonly used in CORS (Cross-Origin Resource Sharing) preflight requests.

   • Use Cases:

     • Determining what methods are allowed on a user resource: OPTIONS /users

   • Response Codes:

     • 200 OK: The allowed methods are returned in the response headers.

3. TRACE (Diagnostic Method)

   • Purpose: TRACE echoes the received request so that the client can see what intermediate servers have altered the request. It is primarily used for debugging purposes.

   • Use Cases:

     • Testing and diagnosing requests and responses along the request chain.

   • Response Codes:

     • 200 OK: The request is echoed back with diagnostic information.

4. CONNECT (Establish Tunnel)

   • Purpose: The CONNECT method is used by clients to establish a network tunnel to the server, often for SSL/TLS connections.

   • Use Cases:

     • Setting up a proxy server connection for secure communication.

   • Response Codes:

     • 200 OK: Connection established.

4. Mapping HTTP Methods to CRUD Operations

The core HTTP methods directly map to standard CRUD (Create, Read, Update, Delete) operations in software development:

CRUD Operation	HTTP Method	Description
Create	POST	Adds a new resource.
Read	GET	Retrieves existing resources.
Update	PUT, PATCH	Updates an existing resource.
Delete	DELETE	Removes a resource.

Understanding this mapping helps developers design APIs that are intuitive, consistent, and aligned with RESTful principles.

5. Best Practices for Using HTTP Methods

1. Use the Correct Method: Always use the appropriate HTTP method that matches the intended action. For instance, use GET for retrieving data and POST for creating new resources.

2. Ensure Idempotency Where Required: Methods like GET, PUT, and DELETE should be idempotent to ensure that multiple identical requests have the same effect, enhancing the reliability of the API.

3. Avoid Data Modification in GET Requests: GET should never alter the state of resources. It must be safe and used purely for data retrieval.

4. Return Appropriate Status Codes: Use standard HTTP status codes to communicate the result of an operation, enhancing the clarity and predictability of the API.

5. Secure Methods Appropriately: Implement proper security measures, such as authentication and authorization, especially for methods that modify or delete resources (POST, PUT, PATCH, DELETE).

6. Conclusion

HTTP methods are fundamental to the operation of REST APIs, providing a standardized way to interact with resources across the web. By mastering these methods and understanding their correct usage, developers can design APIs that are intuitive, efficient, and compliant with RESTful principles. This knowledge serves as the foundation for building robust and user-friendly APIs that effectively meet the needs of modern applications.