////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_CREATE
/// @brief creates documents
///
/// @RESTHEADER{POST /_api/document/{collection},Create document}
///
/// @RESTALLBODYPARAM{data,json,required}
/// A JSON representation of a single document or of an array of documents.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{collection,string,optional}
/// The name of the collection. This is only for backward compatibility.
/// In ArangoDB versions < 3.0, the URL path was */_api/document* and
/// this query parameter was required. This combination still works, but
/// the recommended way is to specify the collection in the URL path.
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
/// Wait until document has been synced to disk.
///
/// @RESTQUERYPARAM{returnNew,boolean,optional}
/// Return additionally the complete new document under the attribute *new*
/// in the result.
///
/// @RESTDESCRIPTION
/// Creates a new document from the document given in the body, unless there
/// is already a document with the *_key* given. If no *_key* is given, a new
/// unique *_key* is generated automatically.
///
/// The body can be an array of documents, in which case all
/// documents in the array are inserted with the same semantics as for a
/// single document. The result body will contain a JSON array of the
/// same length as the input array, and each entry contains the result
/// of the operation for the corresponding input. In case of an error
/// the entry is a document with attributes *error* set to *true* and
/// errorCode set to the error code that has happened.
/// 
/// Possibly given *_id* and *_rev* attributes in the body are always ignored,
/// the URL part or the query parameter collection respectively counts.
///
/// If the document was created successfully, then the *Location* header
/// contains the path to the newly created document. The *ETag* header field
/// contains the revision of the document. Both are only set in the single
/// document case.
///
/// The body of the response contains a JSON object (single document case)
/// with the following attributes:
///
///   - *_id* contains the document handle of the newly created document
///   - *_key* contains the document key
///   - *_rev* contains the document revision
///
/// In the multi case the body is an array of such objects.
///
/// If the collection parameter *waitForSync* is *false*, then the call
/// returns as soon as the document has been accepted. It will not wait
/// until the documents have been synced to disk.
///
/// Optionally, the query parameter *waitForSync* can be used to force
/// synchronization of the document creation 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 this 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 the query parameter *returnNew* is *true*, then, for each
/// generated document, the complete new document is returned under
/// the *new* attribute in the result.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{201}
/// is returned if the documents were created successfully and
/// *waitForSync* was *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the documents were created successfully and
/// *waitForSync* was *false*.
///
/// @RESTRETURNCODE{400}
/// is returned if the body does not contain a valid JSON representation
/// of one document or an array of documents. The response body contains
/// an error document in this case.
///
/// @RESTRETURNCODE{404}
/// is returned if the collection specified by *collection* is unknown.
/// The response body contains an error document in this case.
///
/// @RESTRETURNCODE{409}
/// is returned in the single document case if a document with the
/// same qualifiers in an indexed attribute conflicts with an already
/// existing document and thus violates that unique constraint. The
/// response body contains an error document in this case. In the array
/// case only 201 or 202 is returned, but if an error occurred, the
/// additional HTTP header *X-Arango-Error-Codes* is set, which
/// contains a map of the error codes that occurred together with their
/// multiplicities, as in: *1205:10,1210:17* which means that in 10
/// cases the error 1205 "illegal document handle" and in 17 cases the
/// error 1210 "unique constraint violated" has happened.
///
/// @EXAMPLES
///
/// Create a document in a collection named *products*. Note that the
/// revision identifier might or might not by equal to the auto-generated
/// key.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostCreate1}
///     var cn = "products";
///     db._drop(cn);
///     db._create(cn, { waitForSync: true });
///
///     var url = "/_api/document/" + cn;
///     var body = '{ "Hello": "World" }';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 201);
///
///     logJsonResponse(response);
///   ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Create a document in a collection named *products* with a collection-level
/// *waitForSync* value of *false*.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostAccept1}
///     var cn = "products";
///     db._drop(cn);
///     db._create(cn, { waitForSync: false });
///
///     var url = "/_api/document/" + cn;
///     var body = '{ "Hello": "World" }';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 202);
///
///     logJsonResponse(response);
///   ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Create a document in a collection with a collection-level *waitForSync*
/// value of *false*, but using the *waitForSync* query parameter.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostWait1}
///     var cn = "products";
///     db._drop(cn);
///     db._create(cn, { waitForSync: false });
///
///     var url = "/_api/document/" + cn + "&waitForSync=true";
///     var body = '{ "Hello": "World" }';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 201);
///
///     logJsonResponse(response);
///   ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Unknown collection name
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostUnknownCollection1}
///     var cn = "products";
///     db._drop(cn);
///
///     var url = "/_api/document/" + cn;
///     var body = '{ "Hello": "World" }';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 404);
///
///     logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Illegal document
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostBadJson1}
///     var cn = "products";
///     db._drop(cn);
///
///     var url = "/_api/document/" + cn;
///     var body = '{ 1: "World" }';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 400);
///
///     logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Insert multiple documents:
/// TODO, make this example work.
///
/// @ EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostMulti}
///     var cn = "products";
///     db._drop(cn);
///
///     var url = "/_api/document/" + cn;
///     var body = '[{"Hello":"Earth"}, {"Hello":"Venus"}, {"Hello":"Mars"}]';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 200);
///
///     logJsonResponse(response);
/// @ END_EXAMPLE_ARANGOSH_RUN
///
/// Use of returnNew:
/// TODO, make this example work.
///
/// @ EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostMulti}
///     var cn = "products";
///     db._drop(cn);
///
///     var url = "/_api/document/" + cn + "?returnNew=true";
///     var body = '{"Hello":"World"}';
///
///     var response = logCurlRequest('POST', url, body);
///
///     assert(response.code === 200);
///
///     logJsonResponse(response);
/// @ END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////