To edit a resource in the API, a client will typically send a PUT request
to the server to the URI that represents the resource.
To avoid unintentional loss of data when editing a resource, the server
implementation should preserve all metadata that has not been intentionally
modified by the client. It is also recommended that clients preserve all
metadata that they do not explicitly modify (including foreign markup)
that is provided by the server in order to avoid any potential unintentional
loss of data.
Simultaneous edit of resources
It is possible that more than one client may attempt to edit a resource
at the same time as another client. Clients are not assured in all circumstances
to receive the most recent representation of a resource using GET if the
server is authorizing intermediary caches.
Where a resource does not support explicit locking in the repository, the
following mechanism can be used by clients to verify that the resource
persisted from the server does not differ from the resource as viewed on
the client using the following described support for caching and entity
tags in order to detect any lost updates to a resource.
When a resource is returned from the server, a corresponding HTTP Header
referred to as the ETag may be provided. This ETag is used to alert caching
intermediaries and clients if the latest copy of the resource being held
is consistent with the resource as defined on the server.
The client can choose to do a "Conditional GET" as defined in
RFC2616. The client sends the local ETag header for the resource to the
server by passing its value using the If-None-Match header. If the resource
was not modified the response status code is 304 ("Not Modified"),
and this allows the client to know they have the latest representation
of the resource.