PUT操作中对资源集合去重后保存是否违反REST规范？合规实现及通知

Great question—this is a common edge case when working with collection resources in REST, so let’s break this down clearly.

First: Does this violate REST? #

Short answer: Not necessarily, as long as you align with REST’s core principles and communicate your API’s behavior clearly.

REST focuses on the transfer of resource state—PUT’s semantic is to replace the entire target resource with the state provided in the request. If your business rule defines that the collection resource must contain unique elements, then deduplicating the incoming payload before saving is a valid form of business validation and state normalization—it’s ensuring the resource adheres to its defined schema and constraints.

The only time this becomes a problem is if your API contract explicitly promises to preserve the exact payload sent in PUT requests. If your documentation says "we save exactly what you send", then deduplicating would break that contract. But if your contract states (or you update it to state) that the collection enforces uniqueness, this is fully compliant.

REST-compliant implementation approaches #

Here are the best practices to handle this while staying true to REST principles:

1. Clarify your API contract upfront #

Update your API documentation to explicitly state:

• The collection resource does not allow duplicate elements.
• When a PUT request contains duplicates, the server will automatically remove them and save only unique items.
• Example payloads showing input with duplicates and the corresponding saved output.

This sets clear expectations for users and eliminates confusion.

2. Choose the right HTTP status code #

• 200 OK: Use this when you successfully deduplicate and save the collection. Include the final deduplicated collection in the response body so users can see exactly what was saved. This aligns with PUT’s semantic of returning the updated resource state.
• 400 Bad Request: Use this if your business requires users to submit duplicate-free collections (instead of server-side deduplication). In the response body, specify which elements are duplicated so users can fix the payload before retrying. For example:

  {
    "error": "Duplicate elements found",
    "duplicates": ["el:3", "el:3"]
  }
  

3. Notify users of the deduplication #

To make users aware that their payload was modified, use one or both of these methods:

• Response body warning: Add a top-level field to your JSON response to highlight the change, like:

  {
    "data": ["el:1", "el:2"],
    "warning": "2 duplicate elements were removed from the collection. The saved resource contains only unique items."
  }
  

• HTTP Warning Header: Use the standard Warning header (defined in RFC 7234) to send a machine-readable notification. For example:

  Warning: 299 "Your API Server Name" "Duplicate elements removed from collection; saved only unique items"
  

  This keeps the response body focused on the resource state while still alerting clients to the modification.

Key takeaway #

REST doesn’t forbid server-side normalization of resource state—what matters is transparency and consistency. As long as you document your API’s behavior, return the correct state after modification, and notify users of any changes made to their request, your implementation will be fully compliant.

内容的提问来源于stack exchange，提问作者antohoho