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

@startDocuBlock REST_DOCUMENT_CREATE @brief creates a document

@RESTHEADER{POST /_api/document,Create document}

@RESTALLBODYPARAM{document,json,required} A JSON representation of the document.

@RESTQUERYPARAMETERS

@RESTQUERYPARAM{collection,string,required} The collection name.

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

@RESTDESCRIPTION Creates a new document in the collection named collection. A JSON representation of the document must be passed as the body of the POST request.

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.

The body of the response contains a JSON object with the following attributes:

• _id contains the document handle of the newly created document
• _key contains the document key
• _rev contains the document revision

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 document has 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.

@RESTRETURNCODES

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

@RESTRETURNCODE{202} is returned if the document was created 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 specified by collection is unknown. The response body contains an error document in this case.

@RESTRETURNCODE{409} is returned if a document with the same qualifiers in an indexed attribute conflicts with an already existing document and thus violating that uniq constraint. The response body contains an error document in this case.

@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?collection=" + 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?collection=" + 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?collection=" + 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?collection=" + 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?collection=" + cn;
var body = '{ 1: "World" }';

var response = logCurlRequest('POST', url, body);

assert(response.code === 400);

logJsonResponse(response);

@END_EXAMPLE_ARANGOSH_RUN @endDocuBlock