arangodb/Documentation/DocuBlocks/Rest/Documents/delete_remove_document.md

@startDocuBlock delete_remove_document @brief removes a document

@RESTHEADER{DELETE /_api/document/{document-handle}, Removes a document, removeDocument}

@RESTURLPARAMETERS

@RESTURLPARAM{document-handle,string,required} Removes the document identified by document-handle.

@RESTQUERYPARAMETERS

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

@RESTQUERYPARAM{returnOld,boolean,optional} Return additionally the complete previous revision of the changed document under the attribute old 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 removed document. This option can be used to save some network traffic.

@RESTHEADERPARAMETERS

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

@RESTDESCRIPTION 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 removed document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the document revision.

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 the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

@RESTRETURNCODES

@RESTRETURNCODE{200} is returned if the document was removed successfully and waitForSync was true.

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

@RESTRETURNCODE{404} is returned if the collection or the document was not found. The response body contains an error document in this case.

@RESTRETURNCODE{412} is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.

@EXAMPLES

Using document handle:

@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerDeleteDocument} var cn = "products"; db._drop(cn); db._create(cn, { waitForSync: true }); var document = db.products.save({"hello":"world"});

var url = "/_api/document/" + document._id;

var response = logCurlRequest('DELETE', url);

assert(response.code === 200);

logJsonResponse(response);

~ db._drop(cn); @END_EXAMPLE_ARANGOSH_RUN

Unknown document handle:

@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerDeleteDocumentUnknownHandle} var cn = "products"; db._drop(cn); db._create(cn, { waitForSync: true }); var document = db.products.save({"hello":"world"}); db.products.remove(document._id);

var url = "/_api/document/" + document._id;

var response = logCurlRequest('DELETE', url);

assert(response.code === 404);

logJsonResponse(response);

~ db._drop(cn); @END_EXAMPLE_ARANGOSH_RUN

Revision conflict:

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

var document = db.products.save({"hello":"world"});
var document2 = db.products.save({"hello2":"world"});
var url = "/_api/document/" + document._id;
var headers = {"If-Match":  "\"" + document2._rev + "\""};

var response = logCurlRequest('DELETE', url, "", headers);

assert(response.code === 412);

logJsonResponse(response);

~ db._drop(cn); @END_EXAMPLE_ARANGOSH_RUN @endDocuBlock