Understanding Idempotent, HTTP Request Methods: Best Practices for Developers

Introduction

HTTP Request Methods: HTTP (Hypertext Transfer Protocol) defines a set of request methods that indicate the desired action to be performed on a resource. The main HTTP verbs or methods include GET, POST, PUT, DELETE and PATCH. These verbs have standardized semantics that enable developers to write applications and APIs that handle requests predictably.

In this guide, we will explore the common HTTP methods, their usage and idempotency characteristics.

What is Idempotent?

An idempotent HTTP method is one that has the same end result no matter how many times it is identically repeated. Performing the request once has the same effect as performing it multiple times.

For example, a GET request is idempotent because retrieving the same resource multiple times has no different effect from calling it only once. No matter how many duplicate identical GETs are made, the result will be the same.

On the other hand, a POST request that creates a new resource is not idempotent. Calling the same POST request repeatedly will create multiple new resources rather than just one.

Some key characteristics of idempotent methods:

• Repeated identical requests have no additional side effects.
• The end result stays the same. No new resources are created or state changed on subsequent calls.
• Idempotent methods can be retried automatically in case of failures with no unintended consequences.
• GET, PUT, and DELETE methods are defined to be idempotent.

The idempotency property is important for the safety and reliability of API requests. Methods like GET and DELETE are specified to be idempotent so that clients and systems can freely call them repeatedly with confidence.

Non-idempotent methods like POST require clients to handle retries carefully to avoid inadvertently performing the operation twice. Knowing which HTTP methods are idempotent guides how APIs can be designed and consumed safely.

Overview of Main HTTP Request Methods or HTTP Verbs

The primary HTTP request methods are:

• GET – Retrieve a resource. Should not change any data.
• POST – Create a new resource or trigger an action.
• PUT – Update an existing resource.
• DELETE – Remove/delete a resource.
• PATCH – Partial update of a resource.

There are also lesser used methods like HEAD, OPTIONS, TRACE etc. for specialized needs. But GET, POST, PUT and DELETE make up the bulk of API requests.

GET Requests

GET requests are used to read data without modifying anything on server. Some examples:

GET /api/users (get list of users)
GET /api/users/123 (get user with id 123)  
GET /reports/sales.pdf (download a file)

GET requests only retrieve data, so they should not have side effects like adding new data. They can be cached easily as repeating a GET has the same effect.

POST Requests

POST requests are used to create new resources or trigger actions that don’t naturally fit into any of the other verbs. For example:

POST /api/users (create a new user, return id)
POST /api/orders (create a new order)  
POST /batch (trigger a batch process)

POST can sometimes overlap with PUT functionality when creating a resource, but POST is not idempotent. Repeated identical POST requests will create multiple resources rather than just updating the same one.

PUT Requests

PUT requests are used to update an existing resource identified by its URI. For instance:

PUT /api/users/123 (update user with id 123) 
PUT /api/orders/456 (update order 456)

The PUT request payload will contain the newly updated resource data that should be persisted on the server.

DELETE Requests

As the name suggests, DELETE requests are used to delete resources. For example:

DELETE /api/users/123 (delete user 123)
DELETE /api/orders/456 (delete order 456)

Resources once deleted should not be recoverable via the API. Some APIs use POST for deletes too.

PATCH Requests

PATCH requests are used to make partial updates to resources. For instance:

PATCH /api/users/123 (partially update user 123)  
PATCH /api/orders/456 (partial update order 456)

The PATCH payload only contains fields to be updated rather than the entire resource. PATCH offers more fine-grained update control vs PUT.

Comparison of Key Attributes

Idempotency and safety help determine how requests can be handled by caches, retried automatically etc.

Best Practices for Using HTTP Methods or HTTP Verbs

Here are some best practices around HTTP verbs:

• Use GET only for reading data. Do not cause side effects.
• Use POST for unsafe operations like creating entities or triggering one-off actions.
• Use PUT for full replace update of a resource.
• Use PATCH for partial update of a resource.
• Use DELETE for deleting resources. Do not hide DELETEs as POSTs.
• Use standard verbs where possible instead of inventing custom actions.
• Avoid overloaded POST and PUT endpoints handling multiple entities.
• Follow REST guidelines for resource update and delete using endpoint URIs.

Adhering to standardized method semantics improves API consistency, manageability and client adoption.

Frequently Asked Questions

• Can new custom HTTP methods be created?

Yes, non-standard methods can be created but may not be universally supported across clients. It’s best to stick to standard verbs where possible.

• Is it OK to use POST for update and delete operations?

It is better to use PUT/PATCH and DELETE respectively following conventions. Overloading POST reduces API clarity.

• Should GET requests modify data?

No. GET should only read data. Side effects can cause race conditions and break caching.

• What is the difference between PUT and PATCH?

PUT replaces an entire resource. PATCH allows partial update of individual fields only.

• Can multiple resources be created/updated with one request?

It is better to avoid bulk POST/PUT requests and instead operate on one resource at a time.

Conclusion

HTTP request methods or HTTP verbs are a core aspect of APIs that govern the semantics of operations. Standard methods like GET, POST, PUT, DELETE and PATCH should be used appropriately following established guidelines and conventions. This ensures a uniform and intuitive developer experience. Understanding how to design APIs using the right HTTP methods reduces ambiguity, mistakes and unintended consequences down the road.