@startDocuBlock patch_update_document
@brief updates a document

@RESTHEADER{PATCH /_api/document/{document-handle},Update document, updateDocument}

@RESTALLBODYPARAM{document,json,required}
A JSON representation of a document update as an object.

@RESTURLPARAMETERS

@RESTURLPARAM{document-handle,string,required}
This URL parameter must be a document handle.

@RESTQUERYPARAMETERS

@RESTQUERYPARAM{keepNull,boolean,optional}
If the intention is to delete existing attributes with the patch
command, the URL query parameter *keepNull* can be used with a value
of *false*. This will modify the behavior of the patch command to
remove any attributes from the existing document that are contained
in the patch document with an attribute value of *null*.

@RESTQUERYPARAM{mergeObjects,boolean,optional}
Controls whether objects (not arrays) will be merged if present in
both the existing and the patch document. If set to *false*, the
value in the patch document will overwrite the existing document's
value. If set to *true*, objects will be merged. The default is
*true*.

@RESTQUERYPARAM{waitForSync,boolean,optional}
Wait until document has been synced to disk.

@RESTQUERYPARAM{ignoreRevs,boolean,optional}
By default, or if this is set to *true*, the *_rev* attributes in 
the given document is ignored. If this is set to *false*, then
the *_rev* attribute given in the body document is taken as a
precondition. The document is only updated if the current revision
is the one specified.

@RESTQUERYPARAM{returnOld,boolean,optional}
Return additionally the complete previous revision of the changed 
document under the attribute *old* in the result.

@RESTQUERYPARAM{returnNew,boolean,optional}
Return additionally the complete new document under the attribute *new*
in the result.

@RESTQUERYPARAM{silent,boolean,optional}
If set to *true*, an empty object will be returned as response. No meta-data 
will be returned for the updated document. This option can be used to
save some network traffic.

@RESTHEADERPARAMETERS

@RESTHEADERPARAM{If-Match,string,optional}
You can conditionally update a document based on a target revision id by
using the *if-match* HTTP header.

@RESTDESCRIPTION
Partially updates the document identified by *document-handle*.
The body of the request must contain a JSON document with the
attributes to patch (the patch document). All attributes from the
patch document will be added to the existing document if they do not
yet exist, and overwritten in the existing document if they do exist
there. 

The value of the `_key` attribute as well as attributes
used as sharding keys may not be changed.

Setting an attribute value to *null* in the patch document will cause a
value of *null* to be saved for the attribute by default.

If the *If-Match* header is specified and the revision of the
document in the database is unequal to the given revision, the
precondition is violated.

If *If-Match* is not given and *ignoreRevs* is *false* and there
is a *_rev* attribute in the body and its value does not match
the revision of the document in the database, the precondition is
violated.

If a precondition is violated, an *HTTP 412* is returned.

If the document exists and can be updated, then an *HTTP 201* or
an *HTTP 202* is returned (depending on *waitForSync*, see below),
the *Etag* header field contains the new revision of the document
(in double quotes) and the *Location* header contains a complete URL
under which the document can be queried.

Cluster only: The patch document _may_ contain  
values for the collection's pre-defined shard keys. Values for the shard keys 
are treated as hints to improve performance. Should the shard keys
values be incorrect ArangoDB may answer with a *not found* error

Optionally, the query parameter *waitForSync* can be used to force
synchronization of the updated document operation to disk even in case
that the *waitForSync* flag had been disabled for the entire collection.
Thus, the *waitForSync* query parameter can be used to force synchronization
of just specific operations. To use this, set the *waitForSync* parameter
to *true*. If the *waitForSync* parameter is not specified or set to
*false*, then the collection's default *waitForSync* behavior is
applied. The *waitForSync* query parameter cannot be used to disable
synchronization for collections that have a default *waitForSync* value
of *true*.

If *silent* is not set to *true*, the body of the response contains a JSON 
object with the information about the handle and the revision. The attribute 
*_id* contains the known *document-handle* of the updated document, *_key* 
contains the key which uniquely identifies a document in a given collection, 
and the attribute *_rev* contains the new document revision.

If the query parameter *returnOld* is *true*, then
the complete previous revision of the document
is returned under the *old* attribute in the result.

If the query parameter *returnNew* is *true*, then
the complete new document is returned under
the *new* attribute in the result.

If the document does not exist, then a *HTTP 404* is returned and the
body of the response contains an error document.

@RESTRETURNCODES

@RESTRETURNCODE{201}
is returned if the document was updated successfully and
*waitForSync* was *true*.

@RESTRETURNCODE{202}
is returned if the document was updated successfully and
*waitForSync* was *false*.

@RESTRETURNCODE{400}
is returned if the body does not contain a valid JSON representation
of a document. The response body contains
an error document in this case.

@RESTRETURNCODE{404}
is returned if the collection or the document was not found.

@RESTRETURNCODE{412}
is returned if the precondition was violated. The response will
also contain the found documents' current revisions in the *_rev*
attributes. Additionally, the attributes *_id* and *_key* will be
returned.

@EXAMPLES

Patches an existing document with new content.

@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPatchDocument}
    var cn = "products";
    db._drop(cn);
    db._create(cn);

    var document = db.products.save({"one":"world"});
    var url = "/_api/document/" + document._id;

    var response = logCurlRequest("PATCH", url, { "hello": "world" });

    assert(response.code === 202);

    logJsonResponse(response);
    var response2 = logCurlRequest("PATCH", url, { "numbers": { "one": 1, "two": 2, "three": 3, "empty": null } });
    assert(response2.code === 202);
    logJsonResponse(response2);
    var response3 = logCurlRequest("GET", url);
    assert(response3.code === 200);
    logJsonResponse(response3);
    var response4 = logCurlRequest("PATCH", url + "?keepNull=false", { "hello": null, "numbers": { "four": 4 } });
    assert(response4.code === 202);
    logJsonResponse(response4);
    var response5 = logCurlRequest("GET", url);
    assert(response5.code === 200);
    logJsonResponse(response5);
  ~ db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN

Merging attributes of an object using `mergeObjects`:

@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPatchDocumentMerge}
    var cn = "products";
    db._drop(cn);
    db._create(cn);

    var document = db.products.save({"inhabitants":{"china":1366980000,"india":1263590000,"usa":319220000}});
    var url = "/_api/document/" + document._id;

    var response = logCurlRequest("GET", url);
    assert(response.code === 200);
    logJsonResponse(response);

    var response = logCurlRequest("PATCH", url + "?mergeObjects=true", { "inhabitants": {"indonesia":252164800,"brazil":203553000 }});
    assert(response.code === 202);

    var response2 = logCurlRequest("GET", url);
    assert(response2.code === 200);
    logJsonResponse(response2);

    var response3 = logCurlRequest("PATCH", url + "?mergeObjects=false", { "inhabitants": { "pakistan":188346000 }});
    assert(response3.code === 202);
    logJsonResponse(response3);

    var response4 = logCurlRequest("GET", url);
    assert(response4.code === 200);
    logJsonResponse(response4);
  ~ db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN
@endDocuBlock