[ADP-110] HTTP Methods
Overview
HTTP methods, also known as HTTP verbs, define the desired action to be performed on a resource when making an HTTP request.
Core HTTP Methods
The following HTTP methods are fundamental to RESTful API design:
Core HTTP Methods
| Method | Description | Idempotent | Safe | Reference |
|---|---|---|---|---|
| GET | Used to retrieve a resource or collection of resources. | Yes | Yes | Detailed guidance on GET method |
| POST | Used to create a new resource or submit data for processing. | No | No | Detailed guidance on POST method |
| PUT | Used to update an existing resource by replacing it entirely. | Yes | No | Detailed guidance on PUT method |
| DELETE | Used to remove a resource. | Yes | No | Detailed guidance on DELETE method |
| PATCH | Used to partially modify an existing resource. | Depends | No | Detailed guidance on PATCH method |
GET
- Used to retrieve a resource or collection of resources.
- Should be idempotent and safe (no side effects).
- Detailed guidance on GET method
POST
- Used to create a new resource or submit data for processing.
- Not idempotent, as multiple identical requests may result in multiple resource creations.
- Detailed guidance on POST method
- Can be designed as idempotent, refer to ADP-366: Idempotency Support
PUT
- Used to update an existing resource by replacing it entirely.
- Should be idempotent.
- Detailed guidance on PUT method
DELETE
- Used to remove a resource.
- Should be idempotent.
- Detailed guidance on DELETE method
PATCH
- Used to partially modify an existing resource.
- May or may not be idempotent, depending on the implementation.
- Detailed guidance on PATCH method
- Can be designed as idempotent, refer to ADP-366: Idempotency Support
Additional HTTP Methods
While less common, these methods can be useful in specific scenarios:
HEAD
- Similar to GET, but retrieves only the headers, not the body.
- Useful for checking resource metadata or existence without transferring the entire resource.
OPTIONS
- Used to describe the communication options for the target resource.
- Helpful for CORS preflight requests and API discovery.
Guidance
When designing your API, consider the following principles:
- SHOULD support Idempotency
- Use the appropriate HTTP method for each operation to maintain semantic consistency.
- Ensure that GET requests are always safe and do not modify server state.
- Prefer PUT over PATCH for full resource updates to maintain idempotency.
- Use POST for non-idempotent operations or when the server determines the resource identifier.
- Implement proper error handling and status codes for each method.
Method Safety and Idempotency
- Safe methods (GET, HEAD, OPTIONS) should not modify resources.
- Idempotent methods (GET, PUT, DELETE, HEAD, OPTIONS) should produce the same result when called multiple times.
Considerations for API Design
- Consistency: Use HTTP methods consistently across your API.
- Cacheability: Leverage caching headers, especially for GET requests.
- Statelessness: Design your API to be stateless, with each request containing all necessary information.
- Resource Naming: Use clear, hierarchical resource naming conventions.
Common Pitfalls to Avoid
- Using GET requests to modify server state.
- Implementing non-idempotent PUT requests.
- Overloading POST for all operations instead of using appropriate methods.
- Ignoring the semantic differences between PUT and PATCH.
Implementation Examples
Here's a simple example of how different HTTP methods might be used in a RESTful API for a user resource:
http
GET /users # Retrieve a list of users
GET /users/{id} # Retrieve a specific user
POST /users # Create a new user
PUT /users/{id} # Update a user (full replacement)
PATCH /users/{id} # Partially update a user
DELETE /users/{id} # Delete a user