[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

• 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.
• SHOULD prefer using PATCH for partial updates when unsure.
• 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