PUT vs POST: REST API Creation Guide

POST and PUT are both HTTP methods used for resource manipulation in REST APIs, but they serve different purposes and have distinct characteristics. POST creates resources with server-assigned URIs and is non-idempotent, while PUT creates or replaces resources at client-specified URIs and is idempotent. The choice between them depends on whether the client knows the resource URI in advance and whether you need idempotent behavior.

Contents

• Key Differences Between POST and PUT
• When to Use POST for Resource Creation
• When to Use PUT for Resource Creation
• Idempotency Considerations
• REST API Design Best Practices
• Alternative Approaches

Key Differences Between POST and PUT

The fundamental differences between POST and PUT methods stem from their HTTP specifications and intended use cases:

POST Method:

• Defined in RFC 2616 §9.5 as “used to create a new resource as a subordinate of the resource identified by the Request-URI”
• The server determines the URI of the newly created resource
• Typically returns HTTP 201 (Created) with a Location header pointing to the new resource
• Not idempotent - repeated identical requests can create multiple resources
• Used for actions that don’t have a defined URI mapping

PUT Method:

• Defined in RFC 2616 §9.6 as “used to create or replace a resource at the specified URI”
• The client specifies the exact URI for the resource being created or updated
• Typically returns HTTP 200 (OK) or HTTP 204 (No Content) for successful updates
• Idempotent - repeated identical requests have the same effect as a single request
• Used when the client has full knowledge of the resource identifier

Key Distinction: POST creates resources under server control, while PUT creates or replaces resources at client-specified locations. This affects both the URI assignment process and the idempotency guarantees.

When to Use POST for Resource Creation

POST is the preferred method in these scenarios:

Child Resource Creation:

• When adding a new resource to a collection
• Example: POST /articles creates a new article in the articles collection
• The server assigns the new resource’s URI (e.g., /articles/123)

Unknown Resource URIs:

• When the client doesn’t know the exact URI of the resource being created
• When resources have server-generated identifiers
• When the resource is subordinate to another resource

Non-CRUD Operations:

• For actions that don’t fit traditional CRUD operations
• For processing forms or triggering operations
• For batch operations or complex workflows

According to Microsoft’s API design best practices, “POST requests are used to add a new resource to the collection that the URI identifies.” This aligns with the RESTful principle where POST operates on collections rather than specific resources.

Example: Creating a new user account where the user ID is auto-generated by the server:

http

POST /users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

HTTP/1.1 201 Created
Location: /users/12345

When to Use PUT for Resource Creation

PUT becomes appropriate in these situations:

Client-Specified Resource URIs:

• When the client knows the exact URI for the resource being created
• When using UUIDs or other client-controlled identifiers
• When implementing optimistic concurrency control

Idempotent Resource Creation:

• When you need to ensure that duplicate creation attempts don’t create multiple resources
• When the same request can be safely retried
• When implementing retry logic for robust applications

Full Resource Replacement:

• When creating or completely replacing a resource at a specific URI
• When using PUT for both creation and update operations

As Baeldung explains, “use the PUT method to create a new resource, and the POST method to update an existing resource” is a common pattern, though this can vary based on API design decisions.

Example: Creating a user with a client-specified UUID:

http

PUT /users/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

HTTP/1.1 201 Created

Idempotency Considerations

Idempotency is a crucial factor in choosing between POST and PUT:

PUT Idempotency:

• PUT is idempotent by HTTP specification
• Multiple identical PUT requests produce the same result as a single request
• Makes PUT safe for retries without side effects
• Critical for reliable distributed systems

POST Non-Idempotency:

• POST is not idempotent by default
• Multiple identical POST requests can create multiple resources
• Requires additional server-side logic to prevent duplicate creations
• May need custom idempotency keys or request deduplication

According to RFC 7231, “A request method is considered ‘idempotent’ if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.” The methods GET, HEAD, PUT and DELETE share this property.

Practical Implications:

• Network failures: PUT can be retried safely; POST cannot
• Client retries: PUT won’t cause duplicate resources; POST might
• Concurrency control: PUT works well with optimistic locking

REST API Design Best Practices

When designing REST APIs, consider these best practices:

Consistent URI Patterns:

• POST /resources for creating resources in collections
• PUT /resources/{id} for creating or updating specific resources
• Use clear, hierarchical URI structures

Status Code Selection:

• POST successful creation: HTTP 201 (Created)
• PUT creation/update: HTTP 200 (OK) or HTTP 204 (No Content)
• Include Location header for POST-created resources

Method Semantics:

• Follow REST principles and HTTP semantics
• Use POST for actions that create resources without specifying URI
• Use PUT for operations that target specific resource URIs

Stack Overflow’s API design best practices recommend: “POST /articles/ is for adding a new article, PUT /articles/:id is for updating the article with the given id.”

Client-Side Considerations:

• Document URI patterns clearly for API consumers
• Provide clear error messages for invalid resource URIs
• Consider supporting both methods when appropriate

Alternative Approaches

While the traditional patterns are well-established, some modern APIs adopt alternative approaches:

POST for Both Creation and Updates:

• Some APIs use POST exclusively for both creation and updates
• This simplifies API design but may not follow REST principles strictly
• Common in microservices architectures

PUT for Creation Only:

• Some APIs restrict PUT to resource creation only
• Updates are handled through PATCH or other methods
• This approach emphasizes idempotency for resource creation

Hybrid Approaches:

• Use POST for unknown URIs and PUT for known URIs
• Implement custom idempotency mechanisms for POST requests
• Provide both methods when the use case supports either

As The RESTful cookbook notes, “It’s quite possible, valid and even preferred in some occasions, to use PUT to create resources, or use POST to update resources.”

---

Conclusion

The choice between POST and PUT for resource creation depends on several factors:

1. Resource URI Control: Use POST when the server assigns the resource URI, and PUT when the client specifies it
2. Idempotency Requirements: Choose PUT when you need idempotent behavior for safe retries
3. Collection vs. Individual Resources: Use POST for adding to collections and PUT for targeting specific resources
4. API Consistency: Maintain consistent patterns across your API design

In practice, many REST APIs support both methods where appropriate - POST for general resource creation in collections and PUT for resource creation when the client knows the identifier. This provides flexibility for different use cases while maintaining RESTful principles.

For most applications, starting with the traditional pattern (POST for creation, PUT for updates) is recommended, but be prepared to adapt based on your specific requirements and the needs of your API consumers.

Sources

1. Stack Overflow - What is the difference between POST and PUT in HTTP?
2. RESTful API - Difference between PUT and POST in REST API
3. The Server Side - PUT vs POST: What’s the difference?
4. Stack Overflow Blog - Best practices for REST API design
5. Microsoft Learn - Web API Design Best Practices
6. Baeldung - HTTP PUT vs. POST in REST API
7. The RESTful Cookbook - When to use PUT or POST
8. RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
9. W3C - HTTP/1.1: Method Definitions
10. MScharhag - HTTP methods: Idempotency and Safety