ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[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 ​

MethodDescriptionIdempotentSafeReference
GETUsed to retrieve a resource or collection of resources.YesYesDetailed guidance on GET method
POSTUsed to create a new resource or submit data for processing.NoNoDetailed guidance on POST method
PUTUsed to update an existing resource by replacing it entirely.YesNoDetailed guidance on PUT method
DELETEUsed to remove a resource.YesNoDetailed guidance on DELETE method
PATCHUsed to partially modify an existing resource.DependsNoDetailed guidance on PATCH method
QUERYUsed to retrieve data using a request body when query complexity exceeds what query parameters can reasonably express.YesYesDetailed guidance on QUERY method

GET ​

POST ​

PUT ​

DELETE ​

PATCH ​

QUERY ​

  • Used to retrieve data via a request body, for queries too complex to express safely and cacheably via query parameters alone.
  • Safe and idempotent, like GET, but can carry a request body like POST.
  • Detailed guidance on QUERY method

Additional HTTP Methods ​

While less common, these methods can be useful in specific scenarios:

  • 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, QUERY) should not modify resources.
  • Idempotent methods (GET, PUT, DELETE, HEAD, OPTIONS, QUERY) 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

Client Limitations ​

If the client is limited to only certain HTTP methods, you can use the X-HTTP-Method-Override header to work around this limitation. See ADP-152: X-HTTP-Method-Override for more details.

References ​

Changelog ​

  • 2026-07-08: Add QUERY method (see ADP-116).
  • 2025-02-06: Add related ADPs and references for the client limitations.