PUT replaces or updates a resource and can create it at a client-specified URI when the server permits. It commonly represents an update or upsert in a REST API. section 4.3.1
Map common resource operations to PUT and its alternatives:
- Update one element with PUT /elements/{element identifier}; use PATCH as an alternative for partial updates. section 4.3.6
- Send the complete replacement representation with PUT; PATCH sends only modified properties. section 5.3.4
- Prefer POST for server-generated identifiers; use PUT /products/{product reference} when the consumer supplies a suitable identifier. section 4.3.5
Replacing a product
A product update uses PUT /products/{productReference}. Its path identifies the resource, while the request body contains all properties needed to replace it. A successful update returns the new Product state; creation through the same URI returns 201 Created, distinguishing it from an update returning 200 OK. section 4.5.7 section 5.3.4
PUT is idempotent: repeating an identical request produces the same server effect, although idempotency alone does not prevent overwriting newer data. Complete replacements can also cost more than PATCH at scale. section 12.5.2 section 13.5.5
Figure 4.8 Refer to this mapping when in doubt about choosing an HTTP method for an action. CRUD stands for create, read, update, delete.
Use the CRUD-to-HTTP mapping as a quick reference when choosing PUT, POST, PATCH, GET, or DELETE. section 4.3.1
