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

Fixes some documentation pages for API. fixes #922

This commit is contained in:
Thomas Schmidts 2014-06-30 14:22:17 +02:00
parent 6a12940da0
commit d9b733b997
18 changed files with 420 additions and 1718 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/Books/Users/ConfigureArango/README.mdpp
View File

@ -2,5 +2,5 @@
!SUBSECTION Configuration Files
Options can be specified on the command line or in configuration files. If a
string *@VARIABLE@* occurs in the value, it is replaced by the corresponding
string *Variable* occurs in the value, it is replaced by the corresponding
environment variable.

2
Documentation/Books/Users/HttpDatabase/DatabaseEndpoint.mdpp
View File

@ -8,7 +8,7 @@ regular authentication procedure. If the endpoint is restricted to a list of spe
ArangoDB will check if the requested database is in the list. If not, the request will be turned
down instantly. If yes, then ArangoDB will continue with the regular authentication procedure.
If the request URI was *http://localhost:8529/_db/mydb/...*, then the request to *mydb* will be
If the request URI was *http:// localhost:8529/_db/mydb/...*, then the request to *mydb* will be
allowed (or disallowed) in the following situations:
```

16
Documentation/Books/Users/HttpDatabase/DatabaseManagement.mdpp
View File

@ -10,3 +10,19 @@ databases.
Please note that all database management operations can only be accessed via
the default database (*_system*) and none of the other databases.
!SECTION Managing Databases using HTTP
<!-- js/actions/api-database.js -->
@startDocuBlock JSF_get_api_database_current
<!-- js/actions/api-database.js -->
@startDocuBlock JSF_get_api_database_user
<!-- js/actions/api-database.js -->
@startDocuBlock JSF_get_api_database_list
<!-- js/actions/api-database.js -->
@startDocuBlock JSF_get_api_database_new
<!-- js/actions/api-database.js -->
@startDocuBlock JSF_get_api_database_delete

267
Documentation/Books/Users/HttpDatabase/ManagingDatabasesUsingHttp.mdpp
View File

@ -1,267 +0,0 @@
!CHAPTER Managing Databases using HTTP
`GET /_api/database/current`*(retrieves information about the current database)*
!SUBSECTION Description
Retrieves information about the current database
The response is a JSON object with the following attributes:
* name: the name of the current database
* id: the id of the current database
* path: the filesystem path of the current database
* isSystem: whether or not the current database is the _system database
!SUBSECTION Return codes
`HTTP 200`
is returned if the information was retrieved successfully.
`HTTP 400`
is returned if the request is invalid.
`HTTP 404`
is returned if the database could not be found.
*Examples*
```
unix> curl --dump - http://localhost:8529/_api/database/current
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : {
"name" : "_system",
"id" : "123873",
"path" : "/tmp/vocdir.1653/databases/database-123873",
"isSystem" : true
},
"error" : false,
"code" : 200
}
```
`GET /_api/database/user`*(retrieves a list of all databases the current user can access)*
!SUBSECTION Description
Retrieves the list of all databases the current user can access without specifying a different username or password.
!SUBSECTION Return codes
`HTTP 200`
is returned if the list of database was compiled successfully.
`HTTP 400`
is returned if the request is invalid.
*Examples*
```
unix> curl --dump - http://localhost:8529/_api/database/user
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : [
"_system"
],
"error" : false,
"code" : 200
}
```
`GET /_api/database`*(retrieves a list of all existing databases)*
!SUBSECTION Description
Retrieves the list of all existing databases
Note: retrieving the list of databases is only possible from within the _system database.
!SUBSECTION Return codes
`HTTP 200`
is returned if the list of database was compiled successfully.
`HTTP 400`
is returned if the request is invalid.
`HTTP 403`
is returned if the request was not executed in the _system database.
*Examples*
```
unix> curl --dump - http://localhost:8529/_api/database
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : [
"_system"
],
"error" : false,
"code" : 200
}
```
`POST /_api/database`*(creates a new database)*
!SUBSECTION Body parameters
`body (json,required)`
The body with the name of the database.
!SUBSECTION Description
Creates a new database
The request body must be a JSON object with the attribute name. name must contain a valid [database name](../NamingConventions/DatabaseNames.md).
The request body can optionally contain an attribute users, which then must be a list of user objects to initially create for the new database. Each user object can contain the following attributes:
* username: the user name as a string. This attribute is mandatory.
* passwd: the user password as a string. If not specified, then it defaults to the empty string.
* active: a boolean flag indicating whether the user account should be active or not. The default value is true.
* extra: an optional JSON object with extra user information. The data contained in extra will be stored for the user but not be interpreted further by ArangoDB.
If users is not specified or does not contain any users, a default user root will be created with an empty string password. This ensures that the new database will be accessible after it is created.
The response is a JSON object with the attribute result set to true.
*Note*: creating a new database is only possible from within the _system database.
!SUBSECTION Return codes
`HTTP 201`
is returned if the database was created successfully.
`HTTP 400`
is returned if the request parameters are invalid or if a database with the specified name already exists.
`HTTP 403`
is returned if the request was not executed in the _system database.
`HTTP 409`
is returned if a database with the specified name already exists.
*Examples*
Creating a database named example.
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database
{"name":"example"}
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
{
"result" : true,
"error" : false,
"code" : 201
}
```
Creating a database named mydb with two users.
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database
{"name":"mydb","users":[{"username":"admin","passwd":"secret","active":true},{"username":"tester","passwd":"test001","active":false}]}
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
{
"result" : true,
"error" : false,
"code" : 201
}
```
`DELETE /_api/database/database-name`*(drops an existing database)*
!SUBSECTION URL parameters
`database-name (string,required)`
The name of the database
!SUBSECTION Description
Deletes the database along with all data stored in it.
Note: dropping a database is only possible from within the _system database. The _system database itself cannot be dropped.
!SUBSECTION Return codes
`HTTP 200`
is returned if the database was dropped successfully.
`HTTP 400`
is returned if the request is malformed.
`HTTP 403`
is returned if the request was not executed in the _system database.
`HTTP 404`
is returned if the database could not be found.
*Examples*
```
unix> curl -X DELETE --dump - http://localhost:8529/_api/database/example
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : true,
"error" : false,
"code" : 200
}
```
<!--
@anchor HttpDatabaseCurrent
@copydetails JSF_get_api_database_current
@CLEARPAGE
@anchor HttpDatabaseUser
@copydetails JSF_get_api_database_user
@CLEARPAGE
@anchor HttpDatabaseList
@copydetails JSF_get_api_database_list
@CLEARPAGE
@anchor HttpDatabaseCreate
@copydetails JSF_post_api_database
@CLEARPAGE
@anchor HttpDatabaseDelete
@copydetails JSF_delete_api_database
@CLEARPAGE
-->

15
Documentation/Books/Users/HttpDatabase/NotesOnDatabases.mdpp
View File

@ -10,7 +10,7 @@ in. A new database will only provide access to the system applications shipped
with ArangoDB (that is the web interface at the moment) and no other Foxx
applications until they are explicitly installed for the particular database.
**Database**
!SUBSECTION Database
ArangoDB can handle multiple databases in the same server instance. Databases can be used to logically group and separate data. An ArangoDB database consists of collections and dedicated database-specific worker processes.
A database contains its own collections (which cannot be accessed from other databases), Foxx applications and replication loggers and appliers. Each ArangoDB database contains its own system collections (e.g. _users, _replication, ...).
@ -19,12 +19,12 @@ There will always be at least one database in ArangoDB. This is the default data
When ArangoDB is accessed via its HTTP REST API, the database name is read from the first part of the request URI path (e.g. /_db/_system/...). If the request URI does not contain a database name, the database name is automatically determined by the algorithm described in Database-to-Endpoint Mapping .
**Database Name**
!SUBSECTION Database Name
A single ArangoDB instance can handle multiple databases in parallel. When multiple databases are used, each database must be given an unique name. This name is used to uniquely identify a database. The default database in ArangoDB is named _system.
The database name is a string consisting of only letters, digits and the _ (underscore) and - (dash) characters. User-defined database names must always start with a letter. Database names are case-sensitive.
**Database Organization**
!SUBSECTION Database Organization
A single ArangoDB instance can handle multiple databases in parallel. By default, there will be at least one database which is named _system.
Databases are physically stored in separate sub-directories underneath the database directory, which itself resides in the instance's data directory.
@ -57,12 +57,3 @@ apps/ # the instance's application directory
<database-name>/ # sub-directory for another database
<app-name> # sub-directory for a single application
````
@copydoc GlossaryDatabase
@copydoc GlossaryDatabaseName
@copydoc GlossaryDatabaseOrganization

2
Documentation/Books/Users/HttpDocument/AddressAndEtag.mdpp
View File

@ -21,7 +21,7 @@ Example:
http://localhost:8529/_db/mydb/_api/document/demo/362549736
Note that the following examples use the short URL format for brevity.
**Note**: The following examples use the short URL format for brevity.
Each document also has a document revision or etag with is returned in the
"ETag" HTTP header when requesting a document.

14
Documentation/Books/Users/HttpDocument/README.mdpp
View File

@ -8,7 +8,7 @@ Documents in ArangoDB are JSON objects. These objects can be nested (to any dept
An example document:
***
```js
{
"_id" : "myusers/2345678",
"_key" : "3456789",
@ -25,7 +25,7 @@ An example document:
"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 in
@ -33,11 +33,11 @@ document's unique key in *_key* and and the etag aka document revision in
creating a document. *_id* and *_key* values are immutable once the document
has been created. The *_rev* value is maintained by ArangoDB autonomously.
*Document Handle*
!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 /.
*Document Key*
!SUBSECTION Document Key
A document key uniquely identifies a document in a given collection. 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.
@ -46,14 +46,14 @@ This behavior can be changed on a per-collection level by creating collections w
Using keyOptions it is possible to disallow user-specified keys completely, or to force a specific regime for auto-generating the _key values.
*Document Revision*
!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
**Note**: Revision ids have been returned as integers up to including ArangoDB 1.1
*Document Etag*
!SUBSECTION Document Etag
The document revision enclosed in double quotes. The revision is returned by several HTTP API methods in the Etag HTTP header.

851
Documentation/Books/Users/HttpDocument/WorkingWithDocuments.mdpp
View File

@ -1,845 +1,22 @@
!CHAPTER Working with Documents using REST
`GET /_api/document/document-handle`*(reads a document)*
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_READ
!SUBSECTION URL parameters
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_CREATE
`document-handle (string,required)`
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_REPLACE
The handle of the document.
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_UPDATE
!SUBSECTION HTTP header parameters
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_DELETE
`If-None-Match (string,optional)`
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_READ_HEAD
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.
`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 ad the given etag. Otherwise a *HTTP 412* is returned. As an alternative you can supply the etag in an attribute rev in the URL.
!SUBSECTION Description
Returns the document identified by *document-handle*. The returned document contains two special attributes: _id containing the document handle and _rev containing the revision.
!SUBSECTION codes
`HTTP 200`
is returned if the document was found
`HTTP 304`
is returned if the "If-None-Match" header is given and the document has the same version
`HTTP 404`
is returned if the document or collection was not found
`HTTP 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*
Use a document handle:
```
unix> curl --dump - http://localhost:8529/_api/document/products/272950241
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "272950241"
{
"hello" : "world",
"_id" : "products/272950241",
"_rev" : "272950241",
"_key" : "272950241"
}
```
Use a document handle and an etag:
```
unix> curl --header 'If-None-Match: "273474529"' --dump - http://localhost:8529/_api/document/products/273474529
```
Unknown document handle:
```
unix> curl --dump - http://localhost:8529/_api/document/products/unknownhandle
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "document /_api/document/products/unknownhandle not found",
"code" : 404,
"errorNum" : 1202
}
```
`POST /_api/document`*(creates a document)*
!SUBSECTION Body parameters
`document (json,required)`
A JSON representation of the document.
!SUBSECTION Query parameters
`collection (string,required)`
The collection name.
`createCollection (boolean,optional)`
If this parameter has a value of true or yes, then the collection is created if it does not yet exist. Other values will be ignored so the collection must be present for the operation to succeed.
*Note*: this flag is not supported in a cluster. Using it will result in an error.
`waitForSync (boolean,optional)`
Wait until document has been synced to disk.
!SUBSECTION Description
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 URL 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 URL 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 URL parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.
!SUBSECTION codes
`HTTP 201`
is returned if the document was created successfully and waitForSync was true.
`HTTP 202`
is returned if the document was created successfully and waitForSync was false.
`HTTP 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.
`HTTP 404`
is returned if the collection specified by collection is unknown. The response body contains an error document in this case.
*Examples*
Create a document given a collection named products. Note that the revision identifier might or might not by equal to the auto-generated key.
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products
{ "Hello": "World" }
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "271115233"
location: /_db/_system/_api/document/products/271115233
{
"error" : false,
"_id" : "products/271115233",
"_rev" : "271115233",
"_key" : "271115233"
}
```
Create a document in a collection named products with a collection-level waitForSync value of false.
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products
{ "Hello": "World" }
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "271573985"
location: /_db/_system/_api/document/products/271573985
{
"error" : false,
"_id" : "products/271573985",
"_rev" : "271573985",
"_key" : "271573985"
}
```
Create a document in a collection with a collection-level waitForSync value of false, but using the waitForSync URL parameter.
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products&waitForSync=true
{ "Hello": "World" }
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "272032737"
location: /_db/_system/_api/document/products/272032737
{
"error" : false,
"_id" : "products/272032737",
"_rev" : "272032737",
"_key" : "272032737"
}
```
Create a document in a new, named collection
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products&createCollection=true
{ "Hello": "World" }
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "272491489"
location: /_db/_system/_api/document/products/272491489
{
"error" : false,
"_id" : "products/272491489",
"_rev" : "272491489",
"_key" : "272491489"
}
```
Unknown collection name:
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products
{ "Hello": "World" }
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "collection 'products' not found",
"code" : 404,
"errorNum" : 1203
}
```
Illegal document:
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products
{ 1: "World" }
HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "expecting attribute name",
"code" : 400,
"errorNum" : 600
}
`````
`PUT /_api/document/document-handle`*(replaces a document)*
!SUBSECTION Body parameters
`document (json,required)`
A JSON representation of the new document.
!SUBSECTION URL parameters
`document-handle (string,required)`
The handle of the document.
!SUBSECTION Query parameters
`waitForSync (boolean,optional)`
Wait until document has been synced to disk.
`rev (string,optional)`
You can conditionally replace a document based on a target revision id by using the rev URL parameter.
`policy (string,optional)`
To control the update behavior in case there is a revision mismatch, you can use the policy parameter (see below).
!SUBSECTION HTTP header parameters
`If-Match (string,optional)`
You can conditionally replace a document based on a target revision id by using the if-match HTTP header.
!SUBSECTION Description
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.
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.
Optionally, the URL 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 URL 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 URL 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, the attribute _rev contains the new document revision.
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 URL 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.
!SUBSECTION codes
`HTTP 201`
is returned if the document was replaced successfully and waitForSync was true.
`HTTP 202`
is returned if the document was replaced successfully and waitForSync was false.
`HTTP 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.
`HTTP 404`
is returned if the collection or the document was not found
`HTTP 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:
```
unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/275768289
{"Hello": "you"}
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "276095969"
location: /_db/_system/_api/document/products/275768289
{
"error" : false,
"_id" : "products/275768289",
"_rev" : "276095969",
"_key" : "275768289"
}
```
Unknown document handle:
```
unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/276554721
{}
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "document /_api/document/products/276554721 not found",
"code" : 404,
"errorNum" : 1202
}
```
Produce a revision conflict:
```
unix> curl -X PUT --header 'If-Match: "277668833"' --data-binary @- --dump - http://localhost:8529/_api/document/products/277341153
{"other":"content"}
HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "277341153"
{
"error" : true,
"code" : 412,
"errorNum" : 1200,
"errorMessage" : "precondition failed",
"_id" : "products/277341153",
"_rev" : "277341153",
"_key" : "277341153"
}
```
Last write wins:
```
unix> curl -X PUT --header 'If-Match: "278651873"' --data-binary @- --dump - http://localhost:8529/_api/document/products/278324193?policy=last
{}
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "278914017"
location: /_db/_system/_api/document/products/278324193
{
"error" : false,
"_id" : "products/278324193",
"_rev" : "278914017",
"_key" : "278324193"
}
```
Alternative to header field:
```
unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/279372769?rev=279700449
{"other":"content"}
HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "279372769"
{
"error" : true,
"code" : 412,
"errorNum" : 1200,
"errorMessage" : "precondition failed",
"_id" : "products/279372769",
"_rev" : "279372769",
"_key" : "279372769"
}
```
`PATCH /_api/document/document-handle`*(patches a document)*
!SUBSECTION Body parameters
`document (json,required)`
A JSON representation of the document update.
!SUBSECTION URL parameters
`document-handle (string,required)`
The handle of the document.
!SUBSECTION Query parameters
`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.
`waitForSync (boolean,optional)`
Wait until document has been synced to disk.
`rev (string,optional)`
You can conditionally patch a document based on a target revision id by using the rev URL parameter.
`policy (string,optional)`
To control the update behavior in case there is a revision mismatch, you can use the policy parameter.
!SUBSECTION HTTP header parameters
`If-Match (string,optional)`
You can conditionally patch a document based on a target revision id by using the if-match HTTP header.
!SUBSECTION Description
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 be saved for the attribute by default.
Optionally, the URL parameter waitForSync can be used to force synchronization of the document update operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL 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 URL 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, the attribute _rev contains the new document revision.
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 URL 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).
!SUBSECTION codes
`HTTP 201`
is returned if the document was created successfully and waitForSync was true.
`HTTP 202`
is returned if the document was created successfully and waitForSync was false.
`HTTP 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.
`HTTP 404`
is returned if the collection or the document was not found
`HTTP 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*
patches an existing document with new content.
```
unix> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/280355809
{"hello":"world"}
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "280683489"
location: /_db/_system/_api/document/products/280355809
{
"error" : false,
"_id" : "products/280355809",
"_rev" : "280683489",
"_key" : "280355809"
}
unix> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/280355809
{"numbers":{"one":1,"two":2,"three":3,"empty":null}}
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "281273313"
location: /_db/_system/_api/document/products/280355809
{
"error" : false,
"_id" : "products/280355809",
"_rev" : "281273313",
"_key" : "280355809"
}
unix> curl --dump - http://localhost:8529/_api/document/products/280355809
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "281273313"
{
"one" : "world",
"hello" : "world",
"numbers" : {
"empty" : null,
"one" : 1,
"two" : 2,
"three" : 3
},
"_id" : "products/280355809",
"_rev" : "281273313",
"_key" : "280355809"
}
unix> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/280355809?keepNull=false
{"hello":null,"numbers":{"four":4}}
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "281732065"
location: /_db/_system/_api/document/products/280355809
{
"error" : false,
"_id" : "products/280355809",
"_rev" : "281732065",
"_key" : "280355809"
}
unix> curl --dump - http://localhost:8529/_api/document/products/280355809
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "281732065"
{
"one" : "world",
"numbers" : {
"empty" : null,
"one" : 1,
"two" : 2,
"three" : 3,
"four" : 4
},
"_id" : "products/280355809",
"_rev" : "281732065",
"_key" : "280355809"
}
```
modifies a document, coordinator case in a cluster
`DELETE /_api/document/document-handle`*(deletes a document)*
!SUBSECTION URL parameters
`document-handle (string,required)`
Deletes the document identified by document-handle.
!SUBSECTION Query parameters
`rev (string,optional)`
You can conditionally delete a document based on a target revision id by using the rev URL parameter.
`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).
`waitForSync (boolean,optional)`
Wait until document has been synced to disk.
!SUBSECTION HTTP header parameters
`If-Match (string,optional)`
You can conditionally delete a document based on a target revision id by using the if-match HTTP header.
!SUBSECTION Description
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 deleted document, 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 URL parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.
!SUBSECTION codes
`HTTP 200`
is returned if the document was deleted successfully and waitForSync was true.
`HTTP 202`
is returned if the document was deleted successfully and waitForSync was false.
`HTTP 404`
is returned if the collection or the document was not found. The response body contains an error document in this case.
`HTTP 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:
```
unix> curl -X DELETE --dump - http://localhost:8529/_api/document/products/282256353
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"error" : false,
"_id" : "products/282256353",
"_rev" : "282256353",
"_key" : "282256353"
}
````
Unknown document handle:
```
unix> curl -X DELETE --dump - http://localhost:8529/_api/document/products/282911713
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "document /_api/document/products/282911713 not found",
"code" : 404,
"errorNum" : 1202
}
````
Revision conflict:
```
unix> curl -X DELETE --header 'If-Match: "284484577"' --dump - http://localhost:8529/_api/document/products/284156897
HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "284156897"
{
"error" : true,
"code" : 412,
"errorNum" : 1200,
"errorMessage" : "precondition failed",
"_id" : "products/284156897",
"_rev" : "284156897",
"_key" : "284156897"
}
```
`HEAD /_api/document/document-handle`*(reads a document header)*
!SUBSECTION URL parameters
`document-handle (string,required)`
The handle of the document.
!SUBSECTION Query parameters
`rev (string,optional)`
You can conditionally fetch a document based on a target revision id by using the rev URL parameter.
!SUBSECTION HTTP header parameters
`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, an HTTP 200 response is returned. If the current document revision is identical to the specified etag, then an HTTP 304 is returned.
`If-Match (string,optional)`
You can conditionally fetch a document based on a target revision id by using the if-match HTTP header.
!SUBSECTION Description
Like GET, but only returns the header fields and not the body. You can use this call to get the current revision of a document or check if the document was deleted.
!SUBSECTION codes
`HTTP 200`
is returned if the document was found
`HTTP 304`
is returned if the "If-None-Match" header is given and the document has same version
`HTTP 404`
is returned if the document or collection was not found
`HTTP 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 etag header.
*Examples*
```
unix> curl -X HEAD --dump - http://localhost:8529/_api/document/products/275244001
```
`GET /_api/document`*(reads all documents from collection)*
!SUBSECTION Query parameters
`collection (string,required)`
The name of the collection.
!SUBSECTION Description
Returns a list of all URI for all documents from the collection identified by collection.
!SUBSECTION codes
`HTTP 200`
All went good.
`HTTP 404`
The collection does not exist.
*Examples*
Returns a all ids.
```
unix> curl --dump - http://localhost:8529/_api/document/?collection=products
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"documents" : [
"/_api/document/products/274392033",
"/_api/document/products/274719713",
"/_api/document/products/274064353"
]
}
```
Collection does not exist.
```
unix> curl --dump - http://localhost:8529/_api/document/?collection=doesnotexist
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "collection 'doesnotexist' not found",
"code" : 404,
"errorNum" : 1203
}
```
<!--
@CLEARPAGE
@anchor RestDocumentRead
@copydetails triagens::arango::RestDocumentHandler::readSingleDocument
@CLEARPAGE
@anchor RestDocumentCreate
@copydetails triagens::arango::RestDocumentHandler::createDocument
@CLEARPAGE
@anchor RestDocumentReplace
@copydetails triagens::arango::RestDocumentHandler::replaceDocument
@CLEARPAGE
@anchor RestDocumentUpdate
@copydetails triagens::arango::RestDocumentHandler::updateDocument
@CLEARPAGE
@anchor RestDocumentDelete
@copydetails triagens::arango::RestDocumentHandler::deleteDocument
@CLEARPAGE
@anchor RestDocumentHead
@copydetails triagens::arango::RestDocumentHandler::checkDocument
@CLEARPAGE
@anchor RestDocumentReadAll
@copydetails triagens::arango::RestDocumentHandler::readAllDocuments
-->
<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
@startDocuBlock REST_DOCUMENT_READ_ALL

4
Documentation/Books/Users/HttpEdge/AddressAndEtag.mdpp
View File

@ -21,9 +21,9 @@ the following URL schema:
http://server:port/_db/<database-name>/_api/edge/<document-handle>
Example:
*Example*:
http://localhost:8529/_db/mydb/_api/edge/demo/362549736
Note that the following examples use the short URL format for brevity.
**Note**: that the following examples use the short URL format for brevity.

3
Documentation/Books/Users/HttpEdge/README.mdpp
View File

@ -10,7 +10,8 @@ A graph data model always consists of two collections: the relations between the
nodes in the graphs are stored in an "edges collection", the nodes in the graph
are stored in documents in regular collections.
Example:
*Example*:
- the "edge" collection stores the information that a company's reception is
sub-unit to the services unit and the services unit is sub-unit to the
CEO. You would express this relationship with the *to* and *_to* attributes

287
Documentation/Books/Users/HttpEdge/WorkingWithEdges.mdpp
View File

@ -1,291 +1,32 @@
!CHAPTER Working with Edges using REST
`GET /_api/edge`*(reads an edge)*
*GET /_api/edge/document-handle*
!SUBSECTION Read edge
`GET /_api/edge`
See [HTTP Interface for Documents](../HttpDocuments/README.md) for details.
`POST /_api/edge`*(creates an edge)*
<!-- arangod/RestHandler/RestEdgeHandler.cpp -->
@startDocuBlock API_EDGE_CREATE
!SUBSECTION Body parameters
`edge-document (json,required)`
A JSON representation of the edge document must be passed as the body of the POST request. This JSON object may contain the edge's document key in the _key attribute if needed.
Query parameters
`collection (string,required)`
Creates a new edge in the collection identified by collection name.
`createCollection (boolean,optional)`
If this parameter has a value of true or yes, then the collection is created if it does not yet exist. Other values will be ignored so the collection must be present for the operation to succeed.
*Note*: this flag is not supported in a cluster. Using it will result in an error.
`waitForSync (boolean,optional)`
Wait until the edge document has been synced to disk.
`from (string,required)`
The document handle of the start point must be passed in from handle.
`to (string,required)`
The document handle of the end point must be passed in to handle.
!SUBSECTION Description
Creates a new edge document in the collection named collection. A JSON representation of the document must be passed as the body of the POST request.
The from and to handles are immutable once the edge has been created.
In all other respects the method works like POST /document, see HTTP Interface for Documents for details.
!SUBSECTION Return codes
`HTTP 201`
is returned if the edge was created successfully and waitForSync was true.
`HTTP 202`
is returned if the edge was created successfully.
`HTTP 400`
is returned if the body does not contain a valid JSON representation of an edge, or if the collection specified is not an edge collection. The response body contains an error document in this case.
`HTTP 404`
is returned if the collection specified by collection is unknown. The response body contains an error document in this case.
*Examples*
Create an edge and read it back:
```
unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/edge/?collection=edges&from=vertices/1&to=vertices/2
{"name":"Emil"}
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "287040481"
location: /_db/_system/_api/document/edges/287040481
{
"error" : false,
"_id" : "edges/287040481",
"_rev" : "287040481",
"_key" : "287040481"
}
unix> curl --dump - http://localhost:8529/_api/edge/edges/287040481
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "287040481"
{
"name" : "Emil",
"_id" : "edges/287040481",
"_rev" : "287040481",
"_key" : "287040481",
"_from" : "vertices/1",
"_to" : "vertices/2"
}
```
`PUT /_api/edge`*(updates an edge)*
`PUT /_api/edge/document-handle`
!SUBSECTION Update edge
`PUT /_api/edge`
See [HTTP Interface for Documents](../HttpDocuments/README.md) for details.
`PATCH /_api/edge`*(partially updates an edge)*
*PATCH /_api/edge/document-handle*
!SUBSECTION Partially Update Edge
`PATCH /_api/edge`
See [HTTP Interface for Documents](../HttpDocuments/README.md) for details.
`DELETE /_api/edge`*(deletes an edge)*
`DELETE /_api/edge/document-handle`
!SUBSECTION Delete edge
`DELETE /_api/edge`
See [HTTP Interface for Documents](../HttpDocuments/README.md) for details.
`HEAD /_api/edge`*(reads an edge header)*
`HEAD /_api/edge/document-handle`
!SUBSECTION Read edge header
`HEAD /_api/edge`
See [HTTP Interface for Documents](../HttpDocuments/README.md) for details.
`GET /_api/edges/{collection-id}`*(reads in- or outbound edges)*
!SUBSECTION URL parameters
`collection-id (string,required)`
The id of the collection.
!SUBSECTION Query parameters
`vertex (string,required)`
The id of the start vertex.
`direction (string,optional)`
Selects in or out direction for edges. If not set, any edges are returned.
!SUBSECTION Description
Returns the list of edges starting or ending in the vertex identified by vertex-handle.
*Examples*
Any direction
```
unix> curl --dump - http://localhost:8529/_api/edges/edges?vertex=vertices/1
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"edges" : [
{
"_id" : "edges/6",
"_rev" : "92660705",
"_key" : "6",
"_from" : "vertices/2",
"_to" : "vertices/1",
"$label" : "v2 -> v1"
},
{
"_id" : "edges/7",
"_rev" : "93119457",
"_key" : "7",
"_from" : "vertices/4",
"_to" : "vertices/1",
"$label" : "v4 -> v1"
},
{
"_id" : "edges/5",
"_rev" : "92201953",
"_key" : "5",
"_from" : "vertices/1",
"_to" : "vertices/3",
"$label" : "v1 -> v3"
}
],
"error" : false,
"code" : 200
}
```
In edges
```
unix> curl --dump - http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=in
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"edges" : [
{
"_id" : "edges/6",
"_rev" : "97182689",
"_key" : "6",
"_from" : "vertices/2",
"_to" : "vertices/1",
"$label" : "v2 -> v1"
},
{
"_id" : "edges/7",
"_rev" : "97641441",
"_key" : "7",
"_from" : "vertices/4",
"_to" : "vertices/1",
"$label" : "v4 -> v1"
}
],
"error" : false,
"code" : 200
}
```
Out edges
```
unix> curl --dump - http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=out
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"edges" : [
{
"_id" : "edges/5",
"_rev" : "101245921",
"_key" : "5",
"_from" : "vertices/1",
"_to" : "vertices/3",
"$label" : "v1 -> v3"
}
],
"error" : false,
"code" : 200
}
```
<!--
@anchor RestEdgeRead
@RESTHEADER{GET /_api/edge,reads an edge}
@REST{GET /_api/edge/@FA{document-handle}}
See @ref RestDocument for details.
@anchor RestEdgeCreate
@copydetails triagens::arango::RestEdgeHandler::createDocument
@anchor RestEdgeUpdate
@RESTHEADER{PUT /_api/edge,updates an edge}
@REST{PUT /_api/edge/@FA{document-handle}}
See @ref RestDocument for details.
@anchor RestEdgePatch
@RESTHEADER{PATCH /_api/edge,partially updates an edge}
@REST{PATCH /_api/edge/@FA{document-handle}}
See @ref RestDocument for details.
@anchor RestEdgeDelete
@RESTHEADER{DELETE /_api/edge,deletes an edge}
@REST{DELETE /_api/edge/@FA{document-handle}}
See @ref RestDocument for details.
@anchor RestEdgeHead
@RESTHEADER{HEAD /_api/edge,reads an edge header}
@REST{HEAD /_api/edge/@FA{document-handle}}
See @ref RestDocument for details.
@anchor RestEdgeEdges
@copydetails JSF_get_edges
-->
<!-- js/actions/api-edges.js -->
@startDocuBlock API_EDGE_READINOUTBOUND

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

@ -138,7 +138,6 @@
* [Databases](HttpDatabase/README.md)
* [To-Endpoint](HttpDatabase/DatabaseEndpoint.md)
* [Management](HttpDatabase/DatabaseManagement.md)
* [Managing (http)](HttpDatabase/ManagingDatabasesUsingHttp.md)
* [Note on Databases](HttpDatabase/NotesOnDatabases.md)
* [Documents](HttpDocument/README.md)
* [Address and ETag](HttpDocument/AddressAndEtag.md)

22
Documentation/Books/bot.py
View File

@ -40,18 +40,26 @@ def replaceText(text, pathOfFile, searchText):
# HTTP API changing code
replaced = replaced.replace("@brief","")
replaced = re.sub(r"@RESTHEADER{([\s\w\/\_-]*),([\s\w]*)}", r"###\g<2>\n `\g<1>`", replaced)
replaced = re.sub(r"@RESTHEADER{([\s\w\/\_-]*),([\s\w-]*)}", r"###\g<2>\n `\g<1>`", replaced)
replaced = replaced.replace("@RESTDESCRIPTION","")
replaced = replaced.replace("@RESTURLPARAMS","*URL Parameters*\n")
replaced = replaced.replace("@RESTQUERYPARAMS","*Query Parameters*\n")
replaced = replaced.replace("@RESTHEADERPARAMS","*Header Parameters*\n")
replaced = replaced.replace("@RESTBODYPARAMS","*Body Parameters*\n")
replaced = replaced.replace("@RESTRETURNCODES","*Return Codes*")
replaced = replaced.replace("@RESTURLPARAMETERS","**URL Parameters**\n")
replaced = replaced.replace("@RESTURLPARAMS","**URL Parameters**\n")
replaced = replaced.replace("@RESTQUERYPARAMS","**Query Parameters**\n")
replaced = replaced.replace("@RESTQUERYPARAMETERS","**Query Parameters**\n")
replaced = replaced.replace("@RESTHEADERPARAMS","**Header Parameters**\n")
replaced = replaced.replace("@RESTHEADERPARAMETERS","**Header Parameters**\n")
replaced = replaced.replace("@RESTBODYPARAMS","**Body Parameters**\n")
replaced = replaced.replace("@RESTBODYPARAMETERS","**Body Parameters**\n")
replaced = replaced.replace("@RESTRETURNCODES","**Return Codes**\n")
replaced = replaced.replace("@RESTURLPARAM", "@RESTPARAM")
replaced = replaced.replace("@RESTHEADERPARAM", "@RESTPARAM")
replaced = replaced.replace("@RESTQUERYPARAM", "@RESTPARAM")
replaced = replaced.replace("@RESTBODYPARAM", "@RESTPARAM")
replaced = re.sub(r"@RESTPARAM{([\s\w\-]*),([\s\w\_\|-]*),\s[optional]}", r"* *\g<1>* (\g<3>):", replaced)
replaced = re.sub(r"@RESTPARAM{([\s\w-]*),([\s\w\_\|-]*),\s*(\w+)}", r"* *\g<1>*:", replaced)
replaced = re.sub(r"@RESTRETURNCODE{(.*)}", r"* *HTTP \g<1>*:", replaced)
replaced = re.sub(r"@RESTBODYPARAMS{(.*)}", r"*(\g<1>)*", replaced)
replaced = replaced.replace("@EXAMPLES","*Examples*")
replaced = replaced.replace("@EXAMPLES","**Examples**")
f.write(replaced)
f.close()

290
arangod/RestHandler/RestDocumentHandler.cpp
View File

@ -96,9 +96,10 @@ HttpHandler::status_t RestDocumentHandler::execute () {
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_CREATE
/// @brief creates a document
///
/// @RESTHEADER{POST /_api/document,creates a document}
/// @RESTHEADER{POST /_api/document,Create document}
///
/// @RESTBODYPARAM{document,json,required}
/// A JSON representation of the document.
@ -109,18 +110,18 @@ HttpHandler::status_t RestDocumentHandler::execute () {
/// The collection name.
///
/// @RESTQUERYPARAM{createCollection,boolean,optional}
/// If this parameter has a value of `true` or `yes`, then the collection is
/// If this parameter has a value of *true* or *yes*, then the collection is
/// created if it does not yet exist. Other values will be ignored so the
/// collection must be present for the operation to succeed.
///
/// Note: this flag is not supported in a cluster. Using it will result in an
/// **Note**: this flag is not supported in a cluster. Using it will result in an
/// error.
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
/// Wait until document has been synced to disk.
///
/// @RESTDESCRIPTION
/// Creates a new document in the collection named `collection`. A JSON
/// 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.
///
@ -131,45 +132,45 @@ HttpHandler::status_t RestDocumentHandler::execute () {
/// 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
/// - *_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
/// 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 URL parameter `waitForSync` can be used to force
/// Optionally, the URL parameter *waitForSync* can be used to force
/// synchronisation of the document creation operation to disk even in case that
/// the `waitForSync` flag had been disabled for the entire collection. Thus,
/// the `waitForSync` URL parameter can be used to force synchronisation 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` URL parameter cannot be used to disable synchronisation for
/// collections that have a default `waitForSync` value of `true`.
/// the *waitForSync* flag had been disabled for the entire collection. Thus,
/// the *waitForSync* URL parameter can be used to force synchronisation 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* URL parameter cannot be used to disable synchronisation 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`.
/// 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`.
/// 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
/// is returned if the collection specified by *collection* is unknown. The
/// response body contains an error document in this case.
///
/// @EXAMPLES
///
/// Create a document given a collection named `products`. Note that the
/// Create a document given a collection named *products*. Note that the
/// revision identifier might or might not by equal to the auto-generated
/// key.
///
@ -188,8 +189,8 @@ HttpHandler::status_t RestDocumentHandler::execute () {
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Create a document in a collection named `products` with a collection-level
/// `waitForSync` value of `false`.
/// Create a document in a collection named *products* with a collection-level
/// *waitForSync* value of *false*.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostAccept1}
/// var cn = "products";
@ -206,8 +207,8 @@ HttpHandler::status_t RestDocumentHandler::execute () {
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Create a document in a collection with a collection-level `waitForSync`
/// value of `false`, but using the `waitForSync` URL parameter.
/// Create a document in a collection with a collection-level *waitForSync*
/// value of *false*, but using the *waitForSync* URL parameter.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostWait1}
/// var cn = "products";
@ -271,6 +272,7 @@ HttpHandler::status_t RestDocumentHandler::execute () {
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::createDocument () {
@ -424,9 +426,10 @@ bool RestDocumentHandler::readDocument () {
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_READ
/// @brief reads a single document
///
/// @RESTHEADER{GET /_api/document/`document-handle`,reads a document}
/// @RESTHEADER{GET /_api/document/document-handle,Read document}
///
/// @RESTURLPARAMETERS
///
@ -438,18 +441,18 @@ bool RestDocumentHandler::readDocument () {
/// @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.
/// 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 ad the
/// given etag. Otherwise a `HTTP 412` is returned. As an alternative
/// you can supply the etag in an attribute `rev` in the URL.
/// given etag. Otherwise a *HTTP 412* is returned. As an alternative
/// you can supply the etag in an attribute *rev* in the URL.
///
/// @RESTDESCRIPTION
/// Returns the document identified by `document-handle`. The returned
/// document contains two special attributes: `_id` containing the document
/// handle and `_rev` containing the revision.
/// Returns the document identified by *document-handle*. The returned
/// document contains two special attributes: *_id* containing the document
/// handle and *_rev* containing the revision.
///
/// @RESTRETURNCODES
///
@ -464,10 +467,10 @@ bool RestDocumentHandler::readDocument () {
/// 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 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
///
/// @EXAMPLES
///
@ -515,6 +518,7 @@ bool RestDocumentHandler::readDocument () {
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::readSingleDocument (bool generateBody) {
@ -662,9 +666,10 @@ bool RestDocumentHandler::getDocumentCoordinator (
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_READ_ALL
/// @brief reads all documents from collection
///
/// @RESTHEADER{GET /_api/document,reads all documents from collection}
/// @RESTHEADER{GET /_api/document,Read all documents}
///
/// @RESTQUERYPARAMETERS
///
@ -673,7 +678,7 @@ bool RestDocumentHandler::getDocumentCoordinator (
///
/// @RESTDESCRIPTION
/// Returns a list of all URI for all documents from the collection identified
/// by `collection`.
/// by *collection*.
///
/// @RESTRETURNCODES
///
@ -717,7 +722,7 @@ bool RestDocumentHandler::getDocumentCoordinator (
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::readAllDocuments () {
@ -821,9 +826,10 @@ bool RestDocumentHandler::getAllDocumentsCoordinator (
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_READ_HEAD
/// @brief reads a single document head
///
/// @RESTHEADER{HEAD /_api/document/`document-handle`,reads a document header}
/// @RESTHEADER{HEAD /_api/document/document-handle,Read document header}
///
/// @RESTURLPARAMETERS
///
@ -834,22 +840,22 @@ bool RestDocumentHandler::getAllDocumentsCoordinator (
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally fetch a document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL 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,
/// an `HTTP 200` response is returned. If the current document revision is
/// identical to the specified etag, then an `HTTP 304` is returned.
/// an *HTTP 200* response is returned. If the current document revision is
/// 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.
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// Like `GET`, but only returns the header fields and not the body. You
/// Like *GET*, but only returns the header fields and not the body. You
/// can use this call to get the current revision of a document or check if
/// the document was deleted.
///
@ -861,14 +867,14 @@ bool RestDocumentHandler::getAllDocumentsCoordinator (
/// @RESTRETURNCODE{304}
/// is returned if the "If-None-Match" header is given and the document has
/// 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 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 `etag` header.
/// document's current revision in the *etag* header.
///
/// @EXAMPLES
///
@ -884,6 +890,8 @@ bool RestDocumentHandler::getAllDocumentsCoordinator (
///
/// assert(response.code === 200);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::checkDocument () {
@ -900,9 +908,10 @@ bool RestDocumentHandler::checkDocument () {
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_REPLACE
/// @brief replaces a document
///
/// @RESTHEADER{PUT /_api/document/`document-handle`,replaces a document}
/// @RESTHEADER{PUT /_api/document/document-handle,Replace document}
///
/// @RESTBODYPARAM{document,json,required}
/// A JSON representation of the new document.
@ -919,94 +928,94 @@ bool RestDocumentHandler::checkDocument () {
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally replace a document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL parameter.
///
/// @RESTQUERYPARAM{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the `policy` parameter (see below).
/// can use the *policy* parameter (see below).
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally replace a document based on a target revision id by
/// using the `if-match` HTTP header.
/// 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
/// 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.
///
/// If the new document passed in the body of the request contains the
/// `document-handle` in the attribute `_id` and the revision in `_rev`,
/// *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.
///
/// Optionally, the URL parameter `waitForSync` can be used to force
/// Optionally, the URL parameter *waitForSync* can be used to force
/// synchronisation of the document replacement operation to disk even in case
/// that the `waitForSync` flag had been disabled for the entire collection.
/// Thus, the `waitForSync` URL parameter can be used to force synchronisation
/// 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` URL parameter cannot be used to disable
/// synchronisation for collections that have a default `waitForSync` value
/// of `true`.
/// that the *waitForSync* flag had been disabled for the entire collection.
/// Thus, the *waitForSync* URL parameter can be used to force synchronisation
/// 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* URL parameter cannot be used to disable
/// synchronisation 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, the attribute `_rev`
/// the handle and the revision. The attribute *_id* contains the known
/// *document-handle* of the updated document, the attribute *_rev*
/// contains the new document revision.
///
/// If the document does not exist, then a `HTTP 404` is returned and the
/// 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 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` URL parameter or the
/// `if-match` HTTP header).
/// described mechanisms must be used (either the *rev* URL 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.
/// 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`
/// `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
/// 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
/// id, then by default a *HTTP 412* conflict is returned and no replacement is
/// performed.
///
/// The conditional update behavior can be overriden with the `policy` URL query parameter:
/// The conditional update behavior can be overriden with the *policy* URL query parameter:
///
/// - PUT /_api/document/`document-handle`?policy=`policy`
/// `PUT /_api/document/document-handle?policy=policy`
///
/// If `policy` is set to `error`, then the behavior is as before: replacements
/// 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
/// 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.
/// 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
@ -1016,10 +1025,10 @@ bool RestDocumentHandler::checkDocument () {
/// 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
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
///
/// @EXAMPLES
///
@ -1112,6 +1121,7 @@ bool RestDocumentHandler::checkDocument () {
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::replaceDocument () {
@ -1119,9 +1129,10 @@ bool RestDocumentHandler::replaceDocument () {
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_UPDATE
/// @brief updates a document
///
/// @RESTHEADER{PATCH /_api/document/`document-handle`,patches a document}
/// @RESTHEADER{PATCH /_api/document/document-handle, Patch document}
///
/// @RESTBODYPARAM{document,json,required}
/// A JSON representation of the document update.
@ -1135,72 +1146,72 @@ bool RestDocumentHandler::replaceDocument () {
///
/// @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`.
/// 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`.
/// attribute value of *null*.
///
/// @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` URL parameter.
/// using the *rev* URL parameter.
///
/// @RESTQUERYPARAM{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the `policy` parameter.
/// can use the *policy* parameter.
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally patch a document based on a target revision id by
/// using the `if-match` HTTP header.
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// Partially updates the document identified by `document-handle`.
/// 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` be saved for the attribute by default.
/// Setting an attribute value to *null* in the patch document will cause a
/// value of *null* be saved for the attribute by default.
///
/// Optionally, the URL parameter `waitForSync` can be used to force
/// Optionally, the URL parameter *waitForSync* can be used to force
/// synchronisation of the document update operation to disk even in case
/// that the `waitForSync` flag had been disabled for the entire collection.
/// Thus, the `waitForSync` URL parameter can be used to force synchronisation
/// 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` URL parameter cannot be used to disable
/// synchronisation for collections that have a default `waitForSync` value
/// of `true`.
/// that the *waitForSync* flag had been disabled for the entire collection.
/// Thus, the *waitForSync* URL parameter can be used to force synchronisation
/// 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* URL parameter cannot be used to disable
/// synchronisation 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, the attribute `_rev`
/// the handle and the revision. The attribute *_id* contains the known
/// *document-handle* of the updated document, the attribute *_rev*
/// contains the new document revision.
///
/// If the document does not exist, then a `HTTP 404` is returned and the
/// 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` URL parameter or the `if-match` HTTP header.
/// using either the *rev* URL 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
/// 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 created 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 created successfully and *waitForSync* was
/// *false*.
///
/// @RESTRETURNCODE{400}
/// is returned if the body does not contain a valid JSON representation of a
@ -1210,10 +1221,10 @@ bool RestDocumentHandler::replaceDocument () {
/// 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
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
///
/// @EXAMPLES
///
@ -1245,6 +1256,7 @@ bool RestDocumentHandler::replaceDocument () {
/// assert(response5.code === 200);
/// logJsonResponse(response5);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::updateDocument () {
@ -1526,24 +1538,25 @@ bool RestDocumentHandler::modifyDocumentCoordinator (
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock REST_DOCUMENT_DELETE
/// @brief deletes a document
///
/// @RESTHEADER{DELETE /_api/document/`document-handle`,deletes a document}
/// @RESTHEADER{DELETE /_api/document/document-handle, Deletes document}
///
/// @RESTURLPARAMETERS
///
/// @RESTURLPARAM{document-handle,string,required}
/// Deletes the document identified by `document-handle`.
/// Deletes the document identified by *document-handle*.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally delete a document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL 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
/// can use the *policy* parameter. This is the same as when replacing
/// documents (see replacing documents for more details).
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
@ -1553,39 +1566,39 @@ bool RestDocumentHandler::modifyDocumentCoordinator (
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally delete a document based on a target revision id by
/// using the `if-match` HTTP header.
/// 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 deleted document, the attribute `_rev`
/// the handle and the revision. The attribute *_id* contains the known
/// *document-handle* of the deleted document, 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` URL parameter cannot be used to disable
/// synchronisation 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* URL parameter cannot be used to disable
/// synchronisation for collections that have a default *waitForSync* value
/// of *true*.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// is returned if the document was deleted successfully and `waitForSync` was
/// `true`.
/// is returned if the document was deleted successfully and *waitForSync* was
/// *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the document was deleted successfully and `waitForSync` was
/// `false`.
/// is returned if the document was deleted 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
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
///
/// @EXAMPLES
///
@ -1642,6 +1655,7 @@ bool RestDocumentHandler::modifyDocumentCoordinator (
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestDocumentHandler::deleteDocument () {

270
arangod/RestHandler/RestEdgeHandler.cpp
View File

@ -70,52 +70,52 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request)
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_CREATE
/// @brief creates an edge
///
/// @RESTHEADER{POST /_api/edge,creates an edge}
/// @RESTHEADER{POST /_api/edge,Create edge}
///
/// @RESTBODYPARAM{edge-document,json,required}
/// A JSON representation of the edge document must be passed as the body of
/// the POST request. This JSON object may contain the edge's document key in
/// the `_key` attribute if needed.
/// the *_key* attribute if needed.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{collection,string,required}
/// Creates a new edge in the collection identified by `collection` name.
/// Creates a new edge in the collection identified by *collection* name.
///
/// @RESTQUERYPARAM{createCollection,boolean,optional}
/// If this parameter has a value of `true` or `yes`, then the collection is
/// If this parameter has a value of *true* or *yes*, then the collection is
/// created if it does not yet exist. Other values will be ignored so the
/// collection must be present for the operation to succeed.
///
/// Note: this flag is not supported in a cluster. Using it will result in an
/// **Note**: This flag is not supported in a cluster. Using it will result in an
/// error.
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
/// Wait until the edge document has been synced to disk.
///
/// @RESTQUERYPARAM{from,string,required}
/// The document handle of the start point must be passed in `from` handle.
/// The document handle of the start point must be passed in *from* handle.
///
/// @RESTQUERYPARAM{to,string,required}
/// The document handle of the end point must be passed in `to` handle.
/// The document handle of the end point must be passed in *to* handle.
///
/// @RESTDESCRIPTION
/// Creates a new edge document in the collection named `collection`. A JSON
/// Creates a new edge document in the collection named *collection*. A JSON
/// representation of the document must be passed as the body of the POST
/// request.
///
/// The `from` and `to` handles are immutable once the edge has been created.
/// The *from* and *to* handles are immutable once the edge has been created.
///
/// In all other respects the method works like `POST /document`, see
/// @ref RestDocument for details.
/// In all other respects the method works like *POST /document*.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{201}
/// is returned if the edge was created successfully and `waitForSync` was
/// `true`.
/// is returned if the edge was created successfully and *waitForSync* was
/// *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the edge was created successfully.
@ -126,7 +126,7 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request)
/// The response body contains an error document in this case.
///
/// @RESTRETURNCODE{404}
/// is returned if the collection specified by `collection` is unknown. The
/// is returned if the collection specified by *collection* is unknown. The
/// response body contains an error document in this case.
///
/// @EXAMPLES
@ -156,6 +156,7 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request)
/// db._drop("vertices");
/// db._graphs.remove("graph");
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool RestEdgeHandler::createDocument () {
@ -256,7 +257,7 @@ bool RestEdgeHandler::createDocument () {
string wrongPart;
// Note that in a DBserver in a cluster, the following call will
// actually parse the first part of `from` as a cluster-wide
// actually parse the first part of *from* as a cluster-wide
// collection name, exactly as it is needed here!
res = parseDocumentId(trx.resolver(), from, edge._fromCid, edge._fromKey);
@ -265,7 +266,7 @@ bool RestEdgeHandler::createDocument () {
}
else {
// Note that in a DBserver in a cluster, the following call will
// actually parse the first part of `from` as a cluster-wide
// actually parse the first part of *from* as a cluster-wide
// collection name, exactly as it is needed here!
res = parseDocumentId(trx.resolver(), to, edge._toCid, edge._toKey);
@ -349,9 +350,10 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_READ
/// @brief reads a single edge
///
/// @RESTHEADER{GET /_api/edge/`document-handle`,reads an edge}
/// @RESTHEADER{GET /_api/edge/document-handle, Read edge}
///
/// @RESTURLPARAMETERS
///
@ -363,23 +365,23 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
/// @RESTHEADERPARAM{If-None-Match,string,optional}
/// If the "If-None-Match" header is given, then it must contain exactly one
/// etag. The edge is returned if it has a different revision than the
/// given etag. Otherwise an `HTTP 304` is returned.
/// 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 edge is returned if it has the same revision ad the
/// given etag. Otherwise a `HTTP 412` is returned. As an alternative
/// you can supply the etag in an attribute `rev` in the URL.
/// given etag. Otherwise a *HTTP 412* is returned. As an alternative
/// you can supply the etag in an attribute *rev* in the URL.
///
/// @RESTDESCRIPTION
/// Returns the edge identified by `document-handle`. The returned
/// Returns the edge identified by *document-handle*. The returned
/// edge contains a few special attributes:
///
/// - `_id` contains the document handle
/// - *_id* contains the document handle
///
/// - `_rev` contains the revision
/// - *_rev* contains the revision
///
/// - `_from` and `to` contain the document handles of the connected
/// - *_from* and *to* contain the document handles of the connected
/// vertex documents
///
/// @RESTRETURNCODES
@ -395,16 +397,18 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
/// is returned if the edge or collection was not found
///
/// @RESTRETURNCODE{412}
/// is returned if a "If-Match" header or `rev` is given and the found
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_READ_ALL
/// @brief reads all edges from collection
///
/// @RESTHEADER{GET /_api/edge,reads all edges from collection}
/// @RESTHEADER{GET /_api/edge, Read all edges from collection}
///
/// @RESTQUERYPARAMETERS
///
@ -413,7 +417,7 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
///
/// @RESTDESCRIPTION
/// Returns a list of all URI for all edges from the collection identified
/// by `collection`.
/// by *collection*.
///
/// @RESTRETURNCODES
///
@ -422,12 +426,14 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
///
/// @RESTRETURNCODE{404}
/// The collection does not exist.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_READ_HEAD
/// @brief reads a single edge head
///
/// @RESTHEADER{HEAD /_api/edge/`document-handle`,reads an edge header}
/// @RESTHEADER{HEAD /_api/edge/document-handle, Read edge header}
///
/// @RESTURLPARAMETERS
///
@ -438,16 +444,16 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally fetch an edge document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL parameter.
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally fetch an edge document based on a target revision id by
/// using the `if-match` HTTP header.
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// Like `GET`, but only returns the header fields and not the body. You
/// Like *GET*, but only returns the header fields and not the body. You
/// can use this call to get the current revision of an edge document or check if
/// it was deleted.
///
@ -464,15 +470,17 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
/// is returned if the edge 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 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 `etag` header.
/// document's current revision in the *etag* header.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_REPLACE
/// @brief replaces an edge
///
/// @RESTHEADER{PUT /_api/edge/`document-handle`,replaces an edge}
/// @RESTHEADER{PUT /_api/edge/document-handle,replaces an edge}
///
/// @RESTBODYPARAM{edge,json,required}
/// A JSON representation of the new edge data.
@ -489,95 +497,96 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally replace an edge document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL parameter.
///
/// @RESTQUERYPARAM{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the `policy` parameter (see below).
/// can use the *policy* parameter (see below).
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally replace an edge document based on a target revision id by
/// using the `if-match` HTTP header.
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// Completely updates (i.e. replaces) the edge document identified by `document-handle`.
/// If the edge document exists and can be updated, then a `HTTP 201` is returned
/// Completely updates (i.e. replaces) the edge document identified by *document-handle*.
/// If the edge document exists and can be updated, then a *HTTP 201* is returned
/// and the "ETag" header field contains the new revision of the edge document.
///
/// If the new edge document passed in the body of the request contains the
/// `document-handle` in the attribute `_id` and the revision in `_rev`,
/// *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. Note that the attributes
/// `_from` and `_to` of an edge are immutable and cannot be updated either.
/// relevant in order to avoid confusion when using proxies.
/// **Note**: The attributes
/// *_from* and *_to* of an edge are immutable and cannot be updated either.
///
/// Optionally, the URL parameter `waitForSync` can be used to force
/// Optionally, the URL parameter *waitForSync* can be used to force
/// synchronisation of the edge document replacement operation to disk even in case
/// that the `waitForSync` flag had been disabled for the entire collection.
/// Thus, the `waitForSync` URL parameter can be used to force synchronisation
/// 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` URL parameter cannot be used to disable
/// synchronisation for collections that have a default `waitForSync` value
/// of `true`.
/// that the *waitForSync* flag had been disabled for the entire collection.
/// Thus, the *waitForSync* URL parameter can be used to force synchronisation
/// 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* URL parameter cannot be used to disable
/// synchronisation 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 edge document, the attribute `_rev`
/// the handle and the revision. The attribute *_id* contains the known
/// *document-handle* of the updated edge document, the attribute *_rev*
/// contains the new revision of the edge document.
///
/// If the edge document does not exist, then a `HTTP 404` is returned and the
/// If the edge 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 revision id for
/// conditional replacements (i.e. replacements that will only be executed if
/// the revision id found in the database matches the 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 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` URL parameter or the
/// `if-match` HTTP header).
/// described mechanisms must be used (either the *rev* URL parameter or the
/// *if-match* HTTP header).
/// Regardless which mechanism is used, the parameter needs to contain the target
/// revision id as returned in the `_rev` attribute of an edge document or
/// by an HTTP `etag` header.
/// revision id as returned in the *_rev* attribute of an edge document or
/// by an HTTP *etag* header.
///
/// For example, to conditionally replace an edge document based on a specific revision
/// id, you can use the following request:
///
/// - PUT /_api/document/`document-handle`?rev=`etag`
/// - 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
/// 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 edge 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
/// id, then by default a *HTTP 412* conflict is returned and no replacement is
/// performed.
///
/// The conditional update behavior can be overriden with the `policy` URL query parameter:
/// The conditional update behavior can be overriden with the *policy* URL query parameter:
///
/// - PUT /_api/document/`document-handle`?policy=`policy`
/// - PUT /_api/document/*document-handle*?policy=*policy*
///
/// If `policy` is set to `error`, then the behavior is as before: replacements
/// 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
/// 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.
/// in the request. You can use the *last* *policy* to force replacements.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{201}
/// is returned if the edge document was replaced successfully and `waitForSync` was
/// `true`.
/// is returned if the edge document was replaced successfully and *waitForSync* was
/// *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the edge document was replaced successfully and `waitForSync` was
/// `false`.
/// is returned if the edge document was replaced successfully and *waitForSync* was
/// *false*.
///
/// @RESTRETURNCODE{400}
/// is returned if the body does not contain a valid JSON representation of an edge
@ -588,16 +597,18 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
/// is returned if the collection or the edge document was not found
///
/// @RESTRETURNCODE{412}
/// is returned if a "If-Match" header or `rev` is given and the found
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_UPDATES
/// @brief updates an edge
///
/// @RESTHEADER{PATCH /_api/edge/`document-handle`,patches an edge}
/// @RESTHEADER{PATCH /_api/edge/document-handle, Patches edge}
///
/// @RESTBODYPARAM{document,json,required}
/// A JSON representation of the edge update.
@ -611,75 +622,75 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
///
/// @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`.
/// 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 edge document that are contained in the patch document with an
/// attribute value of `null`.
/// attribute value of *null*.
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
/// Wait until edge document has been synced to disk.
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally patch an edge document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL parameter.
///
/// @RESTQUERYPARAM{policy,string,optional}
/// To control the update behavior in case there is a revision mismatch, you
/// can use the `policy` parameter.
/// can use the *policy* parameter.
///
/// @RESTHEADERPARAMETERS
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally patch an edge document based on a target revision id by
/// using the `if-match` HTTP header.
/// using the *if-match* HTTP header.
///
/// @RESTDESCRIPTION
/// Partially updates the edge document identified by `document-handle`.
/// Partially updates the edge 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 edge document if they do not yet exist, and overwritten
/// in the existing edge 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.
/// Setting an attribute value to *null* in the patch document will cause a
/// value of *null* be saved for the attribute by default.
///
/// Note that internal attributes such as `_key`, `_from` and `_to` are immutable
/// **Note**: Internal attributes such as *_key*, *_from* and *_to* are immutable
/// once set and cannot be updated.
///
/// Optionally, the URL parameter `waitForSync` can be used to force
/// Optionally, the URL parameter *waitForSync* can be used to force
/// synchronisation of the edge document update operation to disk even in case
/// that the `waitForSync` flag had been disabled for the entire collection.
/// Thus, the `waitForSync` URL parameter can be used to force synchronisation
/// 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` URL parameter cannot be used to disable
/// synchronisation for collections that have a default `waitForSync` value
/// of `true`.
/// that the *waitForSync* flag had been disabled for the entire collection.
/// Thus, the *waitForSync* URL parameter can be used to force synchronisation
/// 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* URL parameter cannot be used to disable
/// synchronisation 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 edge document, the attribute `_rev`
/// the handle and the revision. The attribute *_id* contains the known
/// *document-handle* of the updated edge document, the attribute *_rev*
/// contains the new edge document revision.
///
/// If the edge document does not exist, then a `HTTP 404` is returned and the
/// If the edge document does not exist, then a *HTTP 404* is returned and the
/// body of the response contains an error document.
///
/// You can conditionally update an edge document based on a target revision id by
/// using either the `rev` URL parameter or the `if-match` HTTP header.
/// using either the *rev* URL 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
/// can use the *policy* parameter. This is the same as when replacing
/// edge documents (see replacing documents for details).
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{201}
/// is returned if the document was patched successfully and `waitForSync` was
/// `true`.
/// is returned if the document was patched successfully and *waitForSync* was
/// *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the document was patched successfully and `waitForSync` was
/// `false`.
/// is returned if the document was patched successfully and *waitForSync* was
/// *false*.
///
/// @RESTRETURNCODE{400}
/// is returned if the body does not contain a valid JSON representation or when
@ -690,31 +701,33 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
/// is returned if the collection or the edge document was not found
///
/// @RESTRETURNCODE{412}
/// is returned if a "If-Match" header or `rev` is given and the found
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_DELETE
/// @brief deletes an edge
///
/// @RESTHEADER{DELETE /_api/edge/`document-handle`,deletes an edge}
/// @RESTHEADER{DELETE /_api/edge/document-handle, Deletes edge}
///
/// @RESTURLPARAMETERS
///
/// @RESTURLPARAM{document-handle,string,required}
/// Deletes the edge document identified by `document-handle`.
/// Deletes the edge document identified by *document-handle*.
///
/// @RESTQUERYPARAMETERS
///
/// @RESTQUERYPARAM{rev,string,optional}
/// You can conditionally delete an edge document based on a target revision id by
/// using the `rev` URL parameter.
/// using the *rev* URL 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 edge
/// can use the *policy* parameter. This is the same as when replacing edge
/// documents (see replacing edge documents for more details).
///
/// @RESTQUERYPARAM{waitForSync,boolean,optional}
@ -724,39 +737,40 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname,
///
/// @RESTHEADERPARAM{If-Match,string,optional}
/// You can conditionally delete an edge document based on a target revision id by
/// using the `if-match` HTTP header.
/// 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 deleted edge document, the attribute `_rev`
/// the handle and the revision. The attribute *_id* contains the known
/// *document-handle* of the deleted edge document, the attribute *_rev*
/// contains the edge document revision.
///
/// If the `waitForSync` parameter is not specified or set to
/// `false`, then the collection's default `waitForSync` behavior is
/// applied. The `waitForSync` URL parameter cannot be used to disable
/// synchronisation 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* URL parameter cannot be used to disable
/// synchronisation for collections that have a default *waitForSync* value
/// of *true*.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// is returned if the edge document was deleted successfully and `waitForSync` was
/// `true`.
/// is returned if the edge document was deleted successfully and *waitForSync* was
/// *true*.
///
/// @RESTRETURNCODE{202}
/// is returned if the edge document was deleted successfully and `waitForSync` was
/// `false`.
/// is returned if the edge document was deleted successfully and *waitForSync* was
/// *false*.
///
/// @RESTRETURNCODE{404}
/// is returned if the collection or the edge 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
/// 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.
/// document's current revision in the *_rev* attribute. Additionally, the
/// attributes *_id* and *_key* will be returned.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------

81
js/actions/api-database.js
View File

@ -44,15 +44,15 @@ var API = "_api/database";
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @fn JSF_get_api_database_list
/// @startDocuBlock JSF_get_api_database_list
/// @brief retrieves a list of all existing databases
///
/// @RESTHEADER{GET /_api/database,retrieves a list of all existing databases}
/// @RESTHEADER{GET /_api/database, List of databases}
///
/// @RESTDESCRIPTION
/// Retrieves the list of all existing databases
///
/// Note: retrieving the list of databases is only possible from within the `_system` database.
/// **Note**: retrieving the list of databases is only possible from within the *_system* database.
///
/// @RESTRETURNCODES
///
@ -63,9 +63,9 @@ var API = "_api/database";
/// is returned if the request is invalid.
///
/// @RESTRETURNCODE{403}
/// is returned if the request was not executed in the `_system` database.
/// is returned if the request was not executed in the *_system* database.
///
/// *Examples*
/// @EXAMPLES
///
/// @EXAMPLE_ARANGOSH_RUN{RestDatabaseGet}
/// var url = "/_api/database";
@ -75,13 +75,14 @@ var API = "_api/database";
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @fn JSF_get_api_database_user
/// @startDocuBlock JSF_get_api_database_user
/// @brief retrieves a list of all databases the current user can access
///
/// @RESTHEADER{GET /_api/database/user,retrieves a list of all databases the current user can access}
/// @RESTHEADER{GET /_api/database/user, List of accessible databases }
///
/// @RESTDESCRIPTION
/// Retrieves the list of all databases the current user can access without
@ -95,7 +96,7 @@ var API = "_api/database";
/// @RESTRETURNCODE{400}
/// is returned if the request is invalid.
///
/// *Examples*
/// @EXAMPLES
///
/// @EXAMPLE_ARANGOSH_RUN{RestDatabaseGetUser}
/// var url = "/_api/database/user";
@ -105,26 +106,27 @@ var API = "_api/database";
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @fn JSF_get_api_database_current
/// @startDocuBlock JSF_get_api_database_current
/// @brief retrieves information about the current database
///
/// @RESTHEADER{GET /_api/database/current,retrieves information about the current database}
/// @RESTHEADER{GET /_api/database/current, Information of the database}
///
/// @RESTDESCRIPTION
/// Retrieves information about the current database
///
/// The response is a JSON object with the following attributes:
///
/// - `name`: the name of the current database
/// - *name*: the name of the current database
///
/// - `id`: the id of the current database
/// - *id*: the id of the current database
///
/// - `path`: the filesystem path of the current database
/// - *path*: the filesystem path of the current database
///
/// - `isSystem`: whether or not the current database is the `_system` database
/// - *isSystem*: whether or not the current database is the *_system* database
///
/// @RESTRETURNCODES
///
@ -137,7 +139,7 @@ var API = "_api/database";
/// @RESTRETURNCODE{404}
/// is returned if the database could not be found.
///
/// *Examples*
/// @EXAMPLES
///
/// @EXAMPLE_ARANGOSH_RUN{RestDatabaseGetInfo}
/// var url = "/_api/database/current";
@ -147,6 +149,7 @@ var API = "_api/database";
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
function get_api_database (req, res) {
@ -211,9 +214,10 @@ function get_api_database (req, res) {
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_get_api_database_new
/// @brief creates a new database
///
/// @RESTHEADER{POST /_api/database,creates a new database}
/// @RESTHEADER{POST /_api/database, Create database}
///
/// @RESTBODYPARAM{body,json,required}
/// the body with the name of the database.
@ -221,32 +225,32 @@ function get_api_database (req, res) {
/// @RESTDESCRIPTION
/// Creates a new database
///
/// The request body must be a JSON object with the attribute `name`. `name` must
/// The request body must be a JSON object with the attribute *name*. *name* must
/// contain a valid @ref DatabaseNames "database name".
///
/// The request body can optionally contain an attribute `users`, which then
/// The request body can optionally contain an attribute *users*, which then
/// must be a list of user objects to initially create for the new database.
/// Each user object can contain the following attributes:
///
/// - `username`: the user name as a string. This attribute is mandatory.
/// - *username*: the user name as a string. This attribute is mandatory.
///
/// - `passwd`: the user password as a string. If not specified, then it defaults
/// - *passwd*: the user password as a string. If not specified, then it defaults
/// to the empty string.
///
/// - `active`: a boolean flag indicating whether the user accout should be
/// actived or not. The default value is `true`.
/// - *active*: a boolean flag indicating whether the user accout should be
/// actived or not. The default value is *true*.
///
/// - `extra`: an optional JSON object with extra user information. The data
/// contained in `extra` will be stored for the user but not be interpreted
/// - *extra*: an optional JSON object with extra user information. The data
/// contained in *extra* will be stored for the user but not be interpreted
/// further by ArangoDB.
///
/// If `users` is not specified or does not contain any users, a default user
/// `root` will be created with an empty string password. This ensures that the
/// If *users* is not specified or does not contain any users, a default user
/// *root* will be created with an empty string password. This ensures that the
/// new database will be accessible after it is created.
///
/// The response is a JSON object with the attribute `result` set to `true`.
/// The response is a JSON object with the attribute *result* set to *true*.
///
/// Note: creating a new database is only possible from within the `_system` database.
/// **Note**: creating a new database is only possible from within the *_system* database.
///
/// @RESTRETURNCODES
///
@ -258,14 +262,14 @@ function get_api_database (req, res) {
/// specified name already exists.
///
/// @RESTRETURNCODE{403}
/// is returned if the request was not executed in the `_system` database.
/// is returned if the request was not executed in the *_system* database.
///
/// @RESTRETURNCODE{409}
/// is returned if a database with the specified name already exists.
///
/// *Examples*
/// @EXAMPLES
///
/// Creating a database named `example`.
/// Creating a database named *example*.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDatabaseCreate}
/// var url = "/_api/database";
@ -287,7 +291,7 @@ function get_api_database (req, res) {
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Creating a database named `mydb` with two users.
/// Creating a database named *mydb* with two users.
///
/// @EXAMPLE_ARANGOSH_RUN{RestDatabaseCreateUsers}
/// var url = "/_api/database";
@ -320,6 +324,7 @@ function get_api_database (req, res) {
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
function post_api_database (req, res) {
@ -389,9 +394,10 @@ function post_api_database (req, res) {
}
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_get_api_database_delete
/// @brief drop an existing database
///
/// @RESTHEADER{DELETE /_api/database/`database-name`,drops an existing database}
/// @RESTHEADER{DELETE /_api/database/database-name, Drop database}
///
/// @RESTURLPARAMETERS
///
@ -401,8 +407,8 @@ function post_api_database (req, res) {
/// @RESTDESCRIPTION
/// Deletes the database along with all data stored in it.
///
/// Note: dropping a database is only possible from within the `_system` database.
/// The `_system` database itself cannot be dropped.
/// **Note**: dropping a database is only possible from within the *_system* database.
/// The *_system* database itself cannot be dropped.
///
/// @RESTRETURNCODES
///
@ -413,12 +419,12 @@ function post_api_database (req, res) {
/// is returned if the request is malformed.
///
/// @RESTRETURNCODE{403}
/// is returned if the request was not executed in the `_system` database.
/// is returned if the request was not executed in the *_system* database.
///
/// @RESTRETURNCODE{404}
/// is returned if the database could not be found.
///
/// *Examples*
/// @EXAMPLES
///
/// @EXAMPLE_ARANGOSH_RUN{RestDatabaseDrop}
/// var url = "/_api/database";
@ -431,6 +437,7 @@ function post_api_database (req, res) {
///
/// logJsonResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
function delete_api_database (req, res) {

10
js/actions/api-edges.js
View File

@ -39,9 +39,10 @@ var API = "/_api/edges";
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock API_EDGE_READINOUTBOUND
/// @brief get edges
///
/// @RESTHEADER{GET /_api/edges/{collection-id},reads in- or outbound edges}
/// @RESTHEADER{GET /_api/edges/collection-id, Read in- or outbound edges}
///
/// @RESTURLPARAMETERS
///
@ -54,14 +55,14 @@ var API = "/_api/edges";
/// The id of the start vertex.
///
/// @RESTQUERYPARAM{direction,string,optional}
/// Selects `in` or `out` direction for edges. If not set, any edges are
/// Selects *in* or *out* direction for edges. If not set, any edges are
/// returned.
///
/// @RESTDESCRIPTION
/// Returns the list of edges starting or ending in the vertex identified by
/// `vertex-handle`.
/// *vertex-handle*.
///
/// *Examples*
/// @EXAMPLES
///
/// Any direction
///
@ -134,6 +135,7 @@ var API = "/_api/edges";
/// db._drop("vertices");
/// db._graphs.remove("graph");
/// @END_EXAMPLE_ARANGOSH_RUN
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
function get_edges (req, res) {

1
js/server/modules/org/arangodb/foxx/base_middleware.js
View File

@ -144,7 +144,6 @@ BaseMiddleware = function () {
/// "Content-Type": "text/plain"
/// });
/// ```
/// @endcode
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////