8.1 KiB
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_UPDATE
/// @brief updates a document
///
/// @RESTHEADER{PATCH /_api/document/{document-handle},Update document}
///
/// @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.
///
/// @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.
///
/// 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
/// and the Location header contains a complete URL under which the
/// document can be queried.
///
/// 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.
///
/// 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
////////////////////////////////////////////////////////////////////////////////