Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Document 3.0 version of document HTTP API.

This commit is contained in:
Max Neunhoeffer 2016-03-16 14:40:48 +01:00 committed by Simran Brucherseifer
parent e8a03e33ca
commit c38f8be953
13 changed files with 907 additions and 467 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
Documentation/Books/HTTP/Document/AddressAndEtag.mdpp
View File

@ -1,18 +1,158 @@
!CHAPTER Address and ETag of a Document
!CHAPTER Basics and Terminology
All documents in ArangoDB have a [document handle](../Glossary/README.md#document-handle). This handle uniquely identifies
a document. Any document can be retrieved using its unique URI:
!SUBSECTION Documents, Keys, Handles and Revisions
Documents in ArangoDB are JSON objects. These objects can be nested (to
any depth) and may contain lists. Each document has a unique
[primary key](../../Users/Appendix/Glossary.html#document-key) which
identifies it within its collection. Furthermore, each document is
uniquely identified
by its [document handle](../../Users/Appendix/Glossary.html#document-handle)
across all collections in the same database. Different revisions of
the same document (identified by its handle) can be distinguished by their
[document revision](../../Users/Appendix/Glossary.html#document-revision).
Any transaction only ever sees a single revision of a document.
Here is an example document:
```js
{
"_id" : "myusers/3456789",
"_key" : "3456789",
"_rev" : "3456789",
"firstName" : "Hugo",
"lastName" : "Schlonz",
"address" : {
"street" : "Street of Happiness",
"city" : "Heretown"
},
"hobbies" : [
"swimming",
"biking",
"programming"
]
}
```
All documents contain special attributes: the
[document handle](../../Users/Appendix/Glossary.html#document-handle) is stored
as a string in `_id`, the
[document's primary key](../../Users/Appendix/Glossary.html#document-key) in
`_key` and the
[document revision](../../Users/Appendix/Glossary.html#document-revision) in
`_rev`. The value of the `_key` attribute can be specified by the user when
creating a document. `_id` and `_key` values are immutable once the document
has been created. The `_rev` value is maintained by ArangoDB automatically.
!SUBSECTION Document Handle
A document handle uniquely identifies a document in the database. It
is a string and consists of the collection's name and the document key
(`_key` attribute) separated by `/`.
!SUBSECTION Document Key
A document key uniquely identifies a document in the collection it is
stored in. It can and should be used by clients when specific documents
are queried. The document key is stored in the `_key` attribute of
each document. The key values are automatically indexed by ArangoDB in
a collection's primary index. Thus looking up a document by its
key is a fast operation. The _key value of a document is
immutable once the document has been created. By default, ArangoDB will
auto-generate a document key if no _key attribute is specified, and use
the user-specified _key otherwise.
This behavior can be changed on a per-collection level by creating
collections with the `keyOptions` attribute.
Using `keyOptions` it is possible to disallow user-specified keys
completely, or to force a specific regime for auto-generating the `_key`
values.
!SUBSECTION Document Revision
As ArangoDB supports MVCC (Multiple Version Concurrency Control),
documents can exist in more than one
revision. The document revision is the MVCC token used to specify
a particular revision of a document (identified by its `_id`).
It is a string value currently
containing an integer number and is unique within the list of document
revisions for a single document. Document revisions can be used to
conditionally query, update, replace or delete documents in the database. In
order to find a particular revision of a document, you need the document
handle or key, and the document revision.
ArangoDB uses 64bit unsigned integer values to maintain
document revisions internally. When returning document revisions to
clients, ArangoDB will put them into a string to ensure the revision
is not clipped by clients that do not support big integers. Clients
should treat the revision returned by ArangoDB as an opaque string
when they store or use it locally. This will allow ArangoDB to change
the format of revisions later if this should be required. Clients can
use revisions to perform simple equality/non-equality comparisons
(e.g. to check whether a document has changed or not), but they should
not use revision ids to perform greater/less than comparisons with them
to check if a document revision is older than one another, even if this
might work for some cases.
!SUBSECTION Document Etag
ArangoDB tries to adhere to the existing HTTP standard as far as
possible. To this end, results of single document queries have the HTTP
header `ETag` set to the document revision enclosed in double quotes.
The basic operations (create, read, exists, replace, update, delete)
for documents are mapped to the standard HTTP methods (*POST*, *GET*,
*HEAD*, *PUT*, *PATCH* and *DELETE*).
If you modify a document, you can use the *If-Match* field to detect conflicts.
The revision of a document can be checking using the HTTP method *HEAD*.
!SUBSECTION Multiple Documents in a single Request
Beginning with ArangoDB 3.0 the basic document API has been extended
to handle not only single documents but multiple documents in a single
request. This is crucial for performance, in particular in the cluster
situation, in which a single request can involve multiple network hops
within the cluster. Another advantage is that it reduces the overhead of
the HTTP protocol and individual network round trips between the client
and the server. The general idea to perform multiple document operations
in a single request is to use a JSON array of objects in the place of a
single document. As a consequence, document keys, handles and revisions
for preconditions have to be supplied embedded in the individual documents
given. Multiple document operations are restricted to a single document
or edge collections.
See the [API descriptions](WorkingWithDocuments.md) for details.
Note that the *GET*, *HEAD* and *DELETE* HTTP operations generally do
not allow to pass a message body. Thus, they cannot be used to perform
multiple document operations in one request. However, there are other
endpoints to request and delete multiple documents in one request.
FIXME: ADD SENSIBLE LINKS HERE.
!SUBSECTION Address and ETag of a Document
Any document can be retrieved using its unique URI:
http://server:port/_api/document/<document-handle>
For example, assumed that the document handle, which is stored in the *_id*
attribute of the document, is *demo/362549736*, then the URL of that document
For example, assuming that the document handle
is `demo/362549736`, then the URL of that document
is:
http://localhost:8529/_api/document/demo/362549736
The above URL scheme does not specify a [database name](../Glossary/README.md#database-name) explicitly, so the
default database will be used. To explicitly specify the database context, use
The above URL schema does not specify a
[database name](../../Users/Appendix/Glossary..html#database-name)
explicitly, so the
default database `_system` will be used.
To explicitly specify the database context, use
the following URL schema:
http://server:port/_db/<database-name>/_api/document/<document-handle>
@ -23,14 +163,15 @@ Example:
**Note**: The following examples use the short URL format for brevity.
Each document also has a [document revision](../Glossary/README.md#document-revision) or Etag with is returned in the
"ETag" HTTP header when requesting a document.
The [document revision](../../Users/Appendix/Glossary.html#document-revision)
is returned in the "ETag" HTTP header when requesting a document.
If you obtain a document using *GET* and you want to check if a newer revision
If you obtain a document using *GET* and you want to check whether a
newer revision
is available, then you can use the *If-None-Match* header. If the document is
unchanged, a *HTTP 412* (precondition failed) error is returned.
If you want to update or delete a document, then you can use the *If-Match*
header. If the document has changed, then the operation is aborted and a *HTTP
412* error is returned.
If you want to query, replace, update or delete a document, then you
can use the *If-Match* header. If the document has changed, then the
operation is aborted and an *HTTP 412* error is returned.

66
Documentation/Books/HTTP/Document/README.mdpp
View File

@ -1,67 +1,13 @@
!CHAPTER HTTP Interface for Documents
!SUBSECTION Documents, Identifiers, Handles
In this chapter we describe the document REST API of ArangoDB.
We begin with a
This is an introduction to ArangoDB's REST interface for documents.
- [section on the basic approach](AddressAndEtag.md)
Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contain lists. Each document is uniquely identified by its [document handle](../Glossary/README.md#document-handle).
before we proceed with
An example document:
- [the detailed API description](WorkingWithDocuments.md),
```js
{
"_id" : "myusers/3456789",
"_key" : "3456789",
"_rev" : "3456789",
"firstName" : "Hugo",
"lastName" : "Schlonz",
"address" : {
"street" : "Street of Happiness",
"city" : "Heretown"
},
"hobbies" : [
"swimming",
"biking",
"programming"
]
}
```
All documents contain special attributes: the document handle in `_id`, the
document's unique key in `_key` and and the Etag aka [document revision](../Glossary/README.md#document-revision) in
`_rev`. The value of the `_key` attribute can be specified by the user when
creating a document. `_id` and `_key` values are immutable once the document
has been created. The `_rev` value is maintained by ArangoDB autonomously.
!SUBSECTION Document Handle
A document handle uniquely identifies a document in the database. It is a string and consists of the collection's name and the document key (`_key` attribute) separated by `/`.
!SUBSECTION Document Key
A document key uniquely identifies a document in the collection it it stored in. It can and should be used by clients when specific documents are searched. Document keys are stored in the `_key` attribute of documents. The key values are automatically indexed by ArangoDB in a collection's primary index. Thus looking up a document by its key is regularly a fast operation. The _key value of a document is immutable once the document has been created.
By default, ArangoDB will auto-generate a document key if no _key attribute is specified, and use the user-specified _key otherwise.
This behavior can be changed on a per-collection level by creating collections with the keyOptions attribute.
Using keyOptions it is possible to disallow user-specified keys completely, or to force a specific regime for auto-generating the _key values.
!SUBSECTION Document Revision
As ArangoDB supports MVCC, documents can exist in more than one revision. The document revision is the MVCC token used to identify a particular revision of a document. It is a string value currently containing an integer number and is unique within the list of document revisions for a single document. Document revisions can be used to conditionally update, replace or delete documents in the database. In order to find a particular revision of a document, you need the document handle and the document revision.
ArangoDB currently uses 64bit unsigned integer values to maintain document revisions internally. When returning document revisions to clients, ArangoDB will put them into a string to ensure the revision id is not clipped by clients that do not support big integers. Clients should treat the revision id returned by ArangoDB as an opaque string when they store or use it locally. This will allow ArangoDB to change the format of revision ids later if this should be required. Clients can use revisions ids to perform simple equality/non-equality comparisons (e.g. to check whether a document has changed or not), but they should not use revision ids to perform greater/less than comparisons with them to check if a document revision is older than one another, even if this might work for some cases.
**Note**: Revision ids have been returned as integers up to including ArangoDB 1.1
!SUBSECTION Document Etag
The document revision enclosed in double quotes. The revision is returned by several HTTP API methods in the Etag HTTP header.
The basic operations (create, read, update, delete) for documents are mapped to
the standard HTTP methods (*POST*, *GET*, *PUT*, *DELETE*). There is also a
partial update method, which is mapped to the HTTP *PATCH* method.
An identifier for the document revision is returned in the *ETag* HTTP header.
If you modify a document, you can use the *If-Match* field to detect conflicts.
The revision of a document can be checking using the HTTP method *HEAD*.
which has all the gory details.

117
Documentation/Books/HTTP/Document/WorkingWithDocuments.mdpp
View File

@ -3,20 +3,115 @@
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_READ
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_CREATE
!SUBSUBSECTION Changes in 3.0 from 2.8:
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_REPLACE
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_UPDATE
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_DELETE
The *rev* query parameter has been withdrawn. The same effect can be
achieved with the *If-Match* HTTP header.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_READ_HEAD
!SUBSUBSECTION Changes in 3.0 from 2.8:
The *rev* query parameter has been withdrawn. The same effect can be
achieved with the *If-Match* HTTP header.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_READ_ALL
@startDocuBlock REST_DOCUMENT_READ_ALL
!SUBSUBSECTION Changes in 3.0 from 2.8:
The collection name should now be specified in the URL path. The old
way with the URL path */_api/document* and the required query parameter
*collection* still works.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_CREATE
!SUBSUBSECTION Changes in 3.0 from 2.8:
The collection name should now be specified in the URL path. The old
way with the URL path */_api/document* and the required query parameter
*collection* still works. The possibility to insert multiple documents
with one operation is new and the query parameter *returnNew* has been added.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_REPLACE
!SUBSUBSECTION Changes in 3.0 from 2.8:
There are quite some changes in this in comparison to Version 2.8, but
few break existing usage:
- the *rev* query parameter is gone (was duplication of If-Match)
- the *policy* query parameter is gone (was non-sensical)
- the *ignoreRevs* query parameter is new, the default *true* gives
the traditional behaviour as in 2.8
- the *returnNew* and *returnOld* query parameters are new
There should be very few changes to behaviour happening in real-world
situations or drivers. Essentially, one has to replace usage of the
*rev* query parameter by usage of the *If-Match* header. The non-sensical
combination of *If-Match* given and *policy=last* no longer works, but can
easily be achieved by leaving out the *If-Match* header.
The collection name should now be specified in the URL path. The old
way with the URL path */_api/document* and the required query parameter
*collection* still works.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_REPLACE_MULTI
!SUBSUBSECTION Changes in 3.0 from 2.8:
The multi document version is new in 3.0.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_UPDATE
!SUBSUBSECTION Changes in 3.0 from 2.8:
There are quite some changes in this in comparison to Version 2.8, but
few break existing usage:
- the *rev* query parameter is gone (was duplication of If-Match)
- the *policy* query parameter is gone (was non-sensical)
- the *ignoreRevs* query parameter is new, the default *true* gives
the traditional behaviour as in 2.8
- the *returnNew* and *returnOld* query parameters are new
There should be very few changes to behaviour happening in real-world
situations or drivers. Essentially, one has to replace usage of the
*rev* query parameter by usage of the *If-Match* header. The non-sensical
combination of *If-Match* given and *policy=last* no longer works, but can
easily be achieved by leaving out the *If-Match* header.
The collection name should now be specified in the URL path. The old
way with the URL path */_api/document* and the required query parameter
*collection* still works.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_UPDATE_MULTI
!SUBSUBSECTION Changes in 3.0 from 2.8:
The multi document version is new in 3.0.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_DELETE
!SUBSUBSECTION Changes in 3.0 from 2.8:
There are only very few changes in this in comparison to Version 2.8:
- the *rev* query parameter is gone (was duplication of If-Match)
- the *policy* query parameter is gone (was non-sensical)
- the *returnOld* query parameter is new
There should be very few changes to behaviour happening in real-world
situations or drivers. Essentially, one has to replace usage of the
*rev* query parameter by usage of the *If-Match* header. The non-sensical
combination of *If-Match* given and *policy=last* no longer works, but can
easily be achieved by leaving out the *If-Match* header.

2
Documentation/Books/Users/SUMMARY.md
View File

@ -198,4 +198,4 @@
* [Modifying](Appendix/Deprecated/Actions/Modifying.md)
# Link to here from arangosh, actions, foxx, transactions
* [Error codes and meanings](Appendix/ErrorCodes/README.md)
* [Glossary](Appendix/Glossary.md)
* [Glossary](Appendix/Glossary.md)

384
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_CREATE.md
View File

@ -1,162 +1,222 @@
@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
////////////////////////////////////////////////////////////////////////////////
/// @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 operation either succeeds for all documents or
/// fails without adding a single document.
///
/// 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 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/" + 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
////////////////////////////////////////////////////////////////////////////////

47
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_DELETE.md
View File

@ -11,18 +11,13 @@
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally remove a document based on a target revision id by
/// using the *rev* query parameter.
///
/// @RESTQUERYPARAM{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the *policy* parameter. This is the same as when replacing
/// documents (see replacing documents for more details).
///
/// @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.
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-Match,string,optional}
@ -30,27 +25,31 @@
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// 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 new document revision.
/// 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 new 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 *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*.
/// 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*.
/// 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.
@ -121,4 +120,4 @@
/// ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

13
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_READ.md
View File

@ -13,14 +13,13 @@
///
/// @RESTHEADERPARAM{If-None-Match,string,optional}
/// If the "If-None-Match" header is given, then it must contain exactly one
/// etag. The document is returned, if it has a different revision than the
/// given etag. Otherwise an *HTTP 304* is returned.
/// ETag. The document is returned, if it has a different revision than the
/// given ETag. Otherwise an *HTTP 304* is returned.
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// If the "If-Match" header is given, then it must contain exactly one
/// etag. The document is returned, if it has the same revision as the
/// given etag. Otherwise a *HTTP 412* is returned. As an alternative
/// you can supply the etag in an attribute *rev* in the URL.
/// ETag. The document is returned, if it has the same revision as the
/// given ETag. Otherwise a *HTTP 412* is returned.
///
/// @RESTDESCRIPTION
/// Returns the document identified by *document-handle*. The returned
@ -41,7 +40,7 @@
/// is returned if the document or collection was not found
///
/// @RESTRETURNCODE{412}
/// is returned if a "If-Match" header or *rev* is given and the found
/// is returned if an "If-Match" header 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.
@ -95,4 +94,4 @@
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

25
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_READ_ALL.md
View File

@ -2,19 +2,22 @@
/// @startDocuBlock REST_DOCUMENT_READ_ALL
/// @brief reads all documents from collection
///
/// @RESTHEADER{GET /_api/document,Read all documents}
/// @RESTHEADER{GET /_api/document/{collection},Read all documents}
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{collection,string,required}
/// The name of the collection.
/// @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{type,string,optional}
/// The type of the result. The following values are allowed:
///
/// - *id*: returns an array of document ids (*_id* attributes)
/// - *key*: returns an array of document keys (*_key* attributes)
/// - *path*: returns an array of document URI paths. This is the default.
/// - *id*: returns an array of document ids (*_id* attributes)
/// - *key*: returns an array of document keys (*_key* attributes)
/// - *path*: returns an array of document URI paths. This is the default.
///
/// @RESTDESCRIPTION
/// Returns an array of all keys, ids, or URI paths for all documents in the
@ -27,7 +30,7 @@
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// All went good.
/// All went well.
///
/// @RESTRETURNCODE{404}
/// The collection does not exist.
@ -44,7 +47,7 @@
/// db.products.save({"hello1":"world1"});
/// db.products.save({"hello2":"world1"});
/// db.products.save({"hello3":"world1"});
/// var url = "/_api/document/?collection=" + cn;
/// var url = "/_api/document/" + cn;
///
/// var response = logCurlRequest('GET', url);
///
@ -64,7 +67,7 @@
/// db.products.save({"hello1":"world1"});
/// db.products.save({"hello2":"world1"});
/// db.products.save({"hello3":"world1"});
/// var url = "/_api/document/?collection=" + cn + "&type=key";
/// var url = "/_api/document/" + cn + "&type=key";
///
/// var response = logCurlRequest('GET', url);
///
@ -79,7 +82,7 @@
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerReadDocumentAllCollectionDoesNotExist}
/// var cn = "doesnotexist";
/// db._drop(cn);
/// var url = "/_api/document/?collection=" + cn;
/// var url = "/_api/document/" + cn;
///
/// var response = logCurlRequest('GET', url);
///
@ -88,4 +91,4 @@
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

25
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_READ_HEAD.md
View File

@ -9,23 +9,18 @@
/// @RESTURLPARAM{document-handle,string,required}
/// The handle of the document.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally fetch a document based on a target revision id by
/// using the *rev* query parameter.
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-None-Match,string,optional}
/// If the "If-None-Match" header is given, then it must contain exactly one
/// etag. If the current document revision is different to the specified etag,
/// ETag. If the current document revision is not equal to the specified ETag,
/// an *HTTP 200* response is returned. If the current document revision is
/// identical to the specified etag, then an *HTTP 304* is returned.
/// identical to the specified ETag, then an *HTTP 304* is returned.
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally fetch a document based on a target revision id by
/// using the *if-match* HTTP header.
/// If the "If-Match" header is given, then it must contain exactly one
/// ETag. The document is returned, if it has the same revision as the
/// given ETag. Otherwise a *HTTP 412* is returned.
///
/// @RESTDESCRIPTION
/// Like *GET*, but only returns the header fields and not the body. You
@ -39,15 +34,15 @@
///
/// @RESTRETURNCODE{304}
/// is returned if the "If-None-Match" header is given and the document has
/// same version
///*
/// the same version
///
/// @RESTRETURNCODE{404}
/// is returned if the document or collection was not found
///
/// @RESTRETURNCODE{412}
/// is returned if a "If-Match" header or *rev* is given and the found
/// is returned if an "If-Match" header is given and the found
/// document has a different version. The response will also contain the found
/// document's current revision in the *etag* header.
/// document's current revision in the *ETag* header.
///
/// @EXAMPLES
///
@ -66,4 +61,4 @@
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

172
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_REPLACE.md
View File

@ -5,25 +5,32 @@
/// @RESTHEADER{PUT /_api/document/{document-handle},Replace document}
///
/// @RESTALLBODYPARAM{document,json,required}
/// A JSON representation of the new document.
/// A JSON representation of a single document.
///
/// @RESTURLPARAMETERS
///
/// @RESTURLPARAM{document-handle,string,required}
/// The handle of the document.
/// This URL parameter must be a document handle.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
/// Wait until document has been synced to disk.
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally replace a document based on a target revision id by
/// using the *rev* query parameter.
/// @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 replaced if the current revision
/// is the one specified.
///
/// @RESTQUERYPARAM{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the *policy* parameter (see below).
/// @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
///
@ -32,15 +39,26 @@
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// Completely updates (i.e. replaces) the document identified by *document-handle*.
/// If the document exists and can be updated, then a *HTTP 201* is returned
/// and the "ETag" header field contains the new revision of the document.
/// Replaces the document with handle <document-handle> with the one in
/// the body, provided there is such a document and no precondition is
/// violated.
///
/// If the new document passed in the body of the request contains the
/// *document-handle* in the attribute *_id* and the revision in *_rev*,
/// these attributes will be ignored. Only the URI and the "ETag" header are
/// relevant in order to avoid confusion when using proxies.
/// 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 document replacement operation to disk even in case
@ -53,82 +71,46 @@
/// 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.
///
/// 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.
///
/// There are two ways for specifying the targeted document revision id for
/// conditional replacements (i.e. replacements that will only be executed if
/// the revision id found in the database matches the document revision id specified
/// in the request):
/// - specifying the target revision in the *rev* URL query parameter
/// - specifying the target revision in the *if-match* HTTP header
///
///
/// Specifying a target revision is optional, however, if done, only one of the
/// described mechanisms must be used (either the *rev* query parameter or the
/// *if-match* HTTP header).
/// Regardless which mechanism is used, the parameter needs to contain the target
/// document revision id as returned in the *_rev* attribute of a document or
/// by an HTTP *etag* header.
///
/// For example, to conditionally replace a document based on a specific revision
/// id, you can use the following request:
///
///
/// `PUT /_api/document/document-handle?rev=etag`
///
///
/// If a target revision id is provided in the request (e.g. via the *etag* value
/// in the *rev* URL query parameter above), ArangoDB will check that
/// the revision id of the document found in the database is equal to the target
/// revision id provided in the request. If there is a mismatch between the revision
/// id, then by default a *HTTP 412* conflict is returned and no replacement is
/// performed.
///
///
/// The conditional update behavior can be overridden with the *policy* URL query parameter:
///
///
/// `PUT /_api/document/document-handle?policy=policy`
///
///
/// If *policy* is set to *error*, then the behavior is as before: replacements
/// will fail if the revision id found in the database does not match the target
/// revision id specified in the request.
///
/// If *policy* is set to *last*, then the replacement will succeed, even if the
/// revision id found in the database does not match the target revision id specified
/// in the request. You can use the *last* *policy* to force replacements.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{201}
/// is returned if the document was replaced successfully and *waitForSync* was
/// *true*.
/// is returned if the document was replaced successfully and
/// *waitForSync* was *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the document was replaced successfully and *waitForSync* was
/// *false*.
/// is returned if the document was replaced 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.
/// 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
/// is returned if the collection or the document was not found.
///
/// @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.
/// 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
///
@ -188,43 +170,5 @@
/// logJsonResponse(response);
/// ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Last write wins
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerUpdateDocumentIfMatchOtherLastWriteWins}
/// var cn = "products";
/// db._drop(cn);
/// db._create(cn);
///
/// var document = db.products.save({"hello":"world"});
/// var document2 = db.products.replace(document._id,{"other":"content"});
/// var url = "/_api/document/products/" + document._rev + "?policy=last";
/// var headers = {"If-Match": "\"" + document2._rev + "\""};
///
/// var response = logCurlRequest('PUT', url, "{}", headers);
/// assert(response.code === 202);
///
/// logJsonResponse(response);
/// ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Alternative to header fields
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerUpdateDocumentRevOther}
/// 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 + "?rev=" + document2._rev;
///
/// var response = logCurlRequest('PUT', url, '{"other":"content"}');
///
/// assert(response.code === 412);
///
/// logJsonResponse(response);
/// ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

105
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_REPLACE_MULTI.md Normal file
View File

@ -0,0 +1,105 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_REPLACE_MULTI
/// @brief replaces multiple documents
///
/// @RESTHEADER{PUT /_api/document/{collection},Replace documents}
///
/// @RESTALLBODYPARAM{documents,json,required}
/// A JSON representation of an array of documents.
///
/// @RESTURLPARAMETERS
///
/// @RESTURLPARAM{collection,string,required}
/// This URL parameter is the name of the collection in which the
/// documents are replaced.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
/// Wait until the new documents have been synced to disk.
///
/// @RESTQUERYPARAM{ignoreRevs,boolean,optional}
/// By default, or if this is set to *true*, the *_rev* attributes in
/// the given documents are ignored. If this is set to *false*, then
/// any *_rev* attribute given in a body document is taken as a
/// precondition. The document is only replaced if the current revision
/// is the one specified.
///
/// @RESTQUERYPARAM{returnOld,boolean,optional}
/// Return additionally the complete previous revision of the changed
/// documents under the attribute *old* in the result.
///
/// @RESTQUERYPARAM{returnNew,boolean,optional}
/// Return additionally the complete new documents under the attribute *new*
/// in the result.
///
/// @RESTDESCRIPTION
/// Replaces multiple documents in the specified collection with the
/// ones in the body, the replaced documents are specified by the *_key*
/// attributes in the body documents. The operation is only performed,
/// if no precondition is violated and the operation succeeds for all
/// documents or fails without replacing a single document.
///
/// If *ignoreRevs* is *false* and there is a *_rev* attribute in a
/// document in the body and its value does not match the revision of
/// the corresponding document in the database, the precondition is
/// violated.
///
/// If the document exists and can be updated, then an *HTTP 201* or
/// an *HTTP 202* is returned (depending on *waitForSync*, see below).
///
/// Optionally, the query parameter *waitForSync* can be used to force
/// synchronization of the document replacement 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 array with the information
/// about the handle and the revision of the replaced documents. The
/// attribute *_id* contains the known *document-handle* of each 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, for each
/// generated document, the complete previous revision of the document
/// is returned under the *old* attribute in the result.
///
/// 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.
///
/// If any of 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 documents were replaced successfully and
/// *waitForSync* was *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the documents were replaced successfully and
/// *waitForSync* was *false*.
///
/// @RESTRETURNCODE{400}
/// is returned if the body does not contain a valid JSON representation
/// of an array of documents. The response body contains
/// an error document in this case.
///
/// @RESTRETURNCODE{404}
/// is returned if the collection or a 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.
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

127
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_UPDATE.md
View File

@ -2,60 +2,86 @@
/// @startDocuBlock REST_DOCUMENT_UPDATE
/// @brief updates a document
///
/// @RESTHEADER{PATCH /_api/document/{document-handle}, Patch document}
/// @RESTHEADER{PATCH /_api/document/{document-handle},Update document}
///
/// @RESTALLBODYPARAM{document,json,required}
/// A JSON representation of the document update.
/// A JSON representation of a document update as an object.
///
/// @RESTURLPARAMETERS
///
/// @RESTURLPARAM{document-handle,string,required}
/// The handle of the document.
/// 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*.
/// 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*.
/// 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{rev,string,optional}
/// You can conditionally patch a document based on a target revision id by
/// using the *rev* query parameter.
/// @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{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the *policy* parameter.
/// @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 patch a document based on a target revision id by
/// 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 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* be saved for the attribute by default.
/// 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 document update operation to disk even in case
/// 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
@ -65,47 +91,50 @@
/// 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.
/// 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.
///
/// You can conditionally update a document based on a target revision id by
/// using either the *rev* query parameter or the *if-match* HTTP header.
/// To control the update behavior in case there is a revision mismatch, you
/// can use the *policy* parameter. This is the same as when replacing
/// documents (see replacing documents for details).
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{201}
/// is returned if the document was created successfully and *waitForSync* was
/// *true*.
/// is returned if the document was updated successfully and
/// *waitForSync* was *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the document was created successfully and *waitForSync* was
/// *false*.
/// 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.
/// 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
/// is returned if the collection or the document was not found.
///
/// @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.
/// 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.
/// Patches an existing document with new content.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPatchDocument}
/// var cn = "products";
@ -166,4 +195,4 @@
/// ~ db._drop(cn);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

124
Documentation/DocuBlocks/Rest/Documents/REST_DOCUMENT_UPDATE_MULTI.md Normal file
View File

@ -0,0 +1,124 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_UPDATE_MULTI
/// @brief updates multiple documents
///
/// @RESTHEADER{PATCH /_api/document/{collection},Update documents}
///
/// @RESTALLBODYPARAM{documents,json,required}
/// A JSON representation of an array of document updates as objects.
///
/// @RESTURLPARAMETERS
///
/// @RESTURLPARAM{collection,string,required}
/// This URL parameter is the name of the collection in which the
/// documents are updated.
///
/// @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 the new documents have been synced to disk.
///
/// @RESTQUERYPARAM{ignoreRevs,boolean,optional}
/// By default, or if this is set to *true*, the *_rev* attributes in
/// the given documents are ignored. If this is set to *false*, then
/// any *_rev* attribute given in a 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
/// documents under the attribute *old* in the result.
///
/// @RESTQUERYPARAM{returnNew,boolean,optional}
/// Return additionally the complete new documents under the attribute *new*
/// in the result.
///
/// @RESTDESCRIPTION
/// Partially updates documents, the documents to update are specified
/// by the *_key* attributes in the body objects. The body of the
/// request must contain a JSON array of document updates with the
/// attributes to patch (the patch documents). All attributes from the
/// patch documents will be added to the existing documents if they do
/// not yet exist, and overwritten in the existing documents if they do
/// exist there.
///
/// Setting an attribute value to *null* in the patch documents will cause a
/// value of *null* to be saved for the attribute by default.
///
/// If *ignoreRevs* is *false* and there is a *_rev* attribute in a
/// document in the body and its value does not match the revision of
/// the corresponding document in the database, the precondition is
/// violated.
///
/// If the document exists and can be updated, then an *HTTP 201* or
/// an *HTTP 202* is returned (depending on *waitForSync*, see below).
///
/// Optionally, the query parameter *waitForSync* can be used to force
/// synchronization of the document replacement 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 array with the information
/// about the handle and the revision of the replaced documents. The
/// attribute *_id* contains the known *document-handle* of each 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, for each
/// generated document, the complete previous revision of the document
/// is returned under the *old* attribute in the result.
///
/// 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.
///
/// If any of 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 documents were updated successfully and
/// *waitForSync* was *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the documents were updated successfully and
/// *waitForSync* was *false*.
///
/// @RESTRETURNCODE{400}
/// is returned if the body does not contain a valid JSON representation
/// of an array of documents. The response body contains
/// an error document in this case.
///
/// @RESTRETURNCODE{404}
/// is returned if the collection or a 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.
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////