> The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request mess

> The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. So PUT either creates or replaces a resource. Definition of replaced: > 1. take the place of. Source: https://www.google.com.au/search?q=define%3A+replaced https://www.google.com.au/search?q=define%3A+replaced It is pretty clear to me that the spec says PUT completely replaces the state of a resource. So not just a convention but what the spec says. BUT lets take it further. Lets say you do allow partial updates with a PUT. Can you guarantee that your resource's state will always be internally consistent? Say you have two clients, both doing partial PUTs and do the following: Client 1: GET /foo Client 2: GET /foo Client 1: PUT /foo {'bar': 1} Client 2: PUT /foo {'baz': 2} Is the foo resource is a consistent state? For some applications it could be but for many it won't be. And worse for some applications it may not be idempotent and a client's proxy is going to silently retry a PUT that isn't safe to do so. So by allowing partial PUTs we're requiring the developer to consider all combinations a resource could be updated. They then need to communicate the valid combinations to any clients. OR they can split the resource up finer grained resources, each one representing a valid PUT.