[ADP-113] PUT

Overview

The HTTP PUT method is used to update or replace a resource at a specified URI. It is an idempotent method, meaning that multiple identical requests should have the same effect as a single request. PUT is typically used to update a resource with a new state.

Guidance

• For resource updates, MUST favor PATCH over PUT.

WARNING

According to Google AIP 134, PUT's semantic is to replace the entire resource with a new state. However, clients often don't have complete resource information. If we implement PUT correctly, an unintended partial update might occur when fields are missing from the request payload.

There is one edge case where PUT is appropriate: when the request payload is not needed.

PUT /gists/{gist_id}/star
DELETE /gists/{gist_id}/star

This API pair from GitHub's API demonstrates this case - the client only needs the resource ID, and there's no request payload to consider.

• MUST ensure that multiple identical PUT requests have the same effect as a single request.
• MAY include the updated resource representation in the response body.
• MUST use the resource's unique identifier in the URI.
• DRAFT MAY support using a complex key if resource identification requires it.
• MUST replace the entire resource with the new state provided in the request body.
• SHOULD validate and reject requests attempting partial updates.
• MUST validate incoming requests for completeness and correctness.
• MUST return error responses using the HTTP Problem Details format (RFC 9457).
• Regarding omitted fields in the request body, there are two options:
  • MAY choose not to reset the field due to inconvenience, but documentation of this decision is necessary.
  • MUST explicitly specify that omitted fields will be removed from the object.
• If the identifying field is not server-owned, a PUT operation on an empty resource could be interpreted as a POST request, effectively creating a new resource.
• MAY implement PUT operation with If-Match/If-None-Match and ETag to prevent accidental operations.

Responses

• MUST return a 200 OK status code if the update is successful and a representation of the updated resource is included.
• MUST return 201 Created if the resource is newly created from the PUT request.
• SHOULD return 202 Accepted if the request is for an asynchronous operation and it succeeds.
• MUST return a 204 No Content status code if the update is successful and no representation is included.
• MUST return a 404 Not Found status code if the resource does not exist.
• SHOULD return a 409 Conflict status code if there is a conflict in the update process.

Error Responses

All error responses MUST use the HTTP Problem Details format as defined in RFC 9457. For example:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "instance": "/users/123"
}

Examples

1. Update a User Profile

   PUT /users/123
   Content-Type: application/json
   
   {
     "name": "John Doe",
     "email": "john.doe@example.com",
     "age": 30
   }

   Response

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "id": 123,
     "name": "John Doe",
     "email": "john.doe@example.com",
     "age": 30
   }

2. Replace an Existing Product

   PUT /products/456
   Content-Type: application/json
   
   {
     "name": "New Product Name",
     "price": 99.99,
     "stock": 50
   }

   Response

   HTTP/1.1 204 No Content

3. Resource Not Found (with Problem Details)

   PUT /products/789
   Content-Type: application/json
   
   {
     "name": "Non-Existent Product",
     "price": 0,
     "stock": 0
   }

   Response

   HTTP/1.1 404 Not Found
   Content-Type: application/problem+json
   
   {
     "type": "https://example.com/problems/not-found",
     "title": "Resource Not Found",
     "status": 404,
     "detail": "The product with ID 789 does not exist.",
     "instance": "/products/789"
   }

Best Practices

• Consider using a GET request to retrieve the current state before updating a resource.
• For large resources, consider using chunked transfer encoding.
• Implement proper concurrency control mechanisms, such as ETag and conditional requests.
• DRAFT MAY log all PUT operations for auditing and rollback purposes.
• Use consistent Problem Details types across your API for similar error conditions.

Security Considerations

• Implement proper authentication and authorization mechanisms.
• Validate and sanitize input data to prevent injection attacks.
• Use HTTPS to encrypt sensitive data in transit.
• Ensure that Problem Details responses do not leak sensitive information.

References

• RFC 9110: PUT
• MDN Web Docs: HTTP PUT

Changelog

• 2025.03.07: Emphasize the importance of using PATCH over PUT for any resource updates.