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

448 lines
23 KiB
HTML
Raw Blame History

<html><head><title>ArangoDB Manual</title> <style media="screen" type="text/css" style="display:none">body{background-color:white;font:13px Helvetica,arial,freesans,clean,sans-serif;line-height:1.4;color:#333;}#access{font-size:16px;margin-left:12px;display:block;margin-left:10px;margin-right:10px;background-color:#F3F1EE!important;}#access a{border-right:1px solid #DBDEDF;color:#A49F96;display:block;line-height:38px;padding:0 10px;text-decoration:none;}#navigation ul{text-transform:uppercase;list-style:none;margin:0;}#navigation li{float:left;position:relative;}#container{width:920px;margin:0 auto;}a{color:#4183C4;text-decoration:none;}.contents h2{font-size:24px;border-bottom:1px solid #CCC;color:black;}.contents h1{font-size:33px;border-bottom:1px solid #CCC;color:black;}.clearfix:after{content:".";display:block;clear:both;font-size:0;height:0;visibility:hidden;}/**/ *:first-child+html .clearfix{min-height:0;}/**/ * html .clearfix{height:1%;}</style></head><body><div id="container"><img src="images/logo_arangodb.png" width="397" height="67" alt="ArangoDB"><div id="access" role="navigation"><div id="navigation"><ul id="menu-ahome" class="menu"><li><a href="Home.html">Table of contents</a></li> <li><a href="http://www.arangodb.org">ArangoDB homepage</a></li></ul></div><div class="clearfix"></div></div><div>
<!-- Generated by Doxygen 1.7.5.1 -->
</div>
<div class="header">
<div class="headertitle">
<h1>REST Interface for Documents </h1> </div>
</div>
<div class="contents">
<div class="textblock"><p>This is an introduction to ArangoDB's REST interface for documents.</p>
<hr/>
<ul>
<li>
<a class="el" href="RestDocument.html">REST Interface for Documents</a> <ul>
<li>
<a class="el" href="RestDocument.html#RestDocumentIntro">Documents, Identifiers, Handles</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentResource">Address and ETag of an Document</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentHttp">Working with Documents using REST</a> <ul>
<li>
<a class="el" href="RestDocument.html#RestDocumentRead">GET /_api/document/document-handle</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentCreate">POST /_api/document?collection=collection-identifier</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentReplace">PUT /_api/document/document-handle</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentUpdate">PATCH /_api/document/document-handle</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentDelete">DELETE /_api/document/document-handle</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentHead">HEAD /_api/document/document-handle</a> </li>
<li>
<a class="el" href="RestDocument.html#RestDocumentReadAll">GET /_api/document?collection=collection-identifier</a> </li>
</ul>
</li>
</ul>
</li>
</ul>
<hr/>
<h2><a class="anchor" id="RestDocumentIntro"></a>
Documents, Identifiers, Handles</h2>
<p><b>Document</b>: Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contains lists. Each document is unique identified by its document handle. </p>
<p>For example:</p>
<div class="fragment"><pre class="fragment">{
"_id" : "1234567/2345678",
"_rev" : "3456789",
"firstName" : "Hugo",
"lastName" : "Schlonz",
"address" : {
"street" : "Strasse 1",
"city" : "Hier"
},
"hobbies" : [
"swimming",
"biking",
"programming"
]
}
</pre></div><p>All documents contain two special fields, the document handle in <code>_id</code> and the etag aka document revision in <code>_rev</code>.</p>
<p><b>Document Handle</b>: A document handle uniquely identifies a document in the database. It is a string and consists of a collection identifier and a document identifier separated by <code>/</code>. </p>
<p><b>Document Identifier</b>: A document identifier identifies a document in a given collection. It is an integer and is unique within the collection of the document. </p>
<p><b>Document Revision</b>: As AvocaodDB 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 an integer and unique within the list of document revision for a single document. Earlier revision of a document have smaller numbers. In order to find a particular revision of a document, you need the document handle and the document revision. </p>
<p><b>Document Etag</b>: The document revision enclosed in double quotes. </p>
<p>The basic operations (create, read, update, delete) for documents are mapped to the standard HTTP methods (POST, GET, PUT, DELETE). An identifier for the document revision is returned in the "ETag" header field. If you modify a document, you can use the "If-Match" field to detect conflicts. The revision of a document can be checking using the HTTP method HEAD.</p>
<h2><a class="anchor" id="RestDocumentResource"></a>
Address and ETag of an Document</h2>
<p>All documents in ArangoDB have a document handle. This handle uniquely defines a document and is managed by ArangoDB. All documents are found under the URI:</p>
<p><code><a href="http://">http://</a><em>server</em>:<em>port</em>/_api/document/<em>document-handle</em></code></p>
<p>For example: Assume that the document handle, which is stored in the <code>_id</code> field of the document, is <code>7254820/362549736</code>, then the URL of that document is:</p>
<p><code><a href="http://localhost:8529/_api/document/7254820/362549736">http://localhost:8529/_api/document/7254820/362549736</a></code></p>
<p>Each document also has a document revision or etag with is returned in the "ETag" header field when requesting a document.</p>
<p>If you obtain a document using <code>GET</code> and you want to check if a newer revision is available, then you can use the "If-None-Match" header. If the document is unchanged, a <code>HTTP 412</code> is returned.</p>
<p>If you want to update or delete a document, then you can use the "If-Match" header. If the document has changed, then the operation is aborted and a <code>HTTP 412</code> is returned.</p>
<h2><a class="anchor" id="RestDocumentHttp"></a>
Working with Documents using REST</h2>
<p><a class="anchor" id="RestDocumentRead"></a> <hr/>
<em>GET /_api/document</em> (reads a document)<hr/>
<br/>
<code><b>GET /_api/document/<em>document-handle</em></b></code></p>
<p>Returns the document identified by <em>document-handle</em>. The returned document contains two special attributes: <code>_id</code> containing the document handle and <code>_rev</code> containing the revision.</p>
<p>If the document exists, then a <code>HTTP 200</code> is returned and the JSON representation of the document is the body of the response.</p>
<p>If the <em>document-handle</em> points to a non-existing document, then a <code>HTTP 404</code> is returned and the body contains an error document.</p>
<p>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 a <code>HTTP 304</code> is returned.</p>
<p>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 <code>HTTP 412</code> is returned. As an alternative you can supply the etag in an attribute <code>rev</code> in the URL.</p>
<p><b>Examples</b><br/>
</p>
<p>Use a document handle:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/document/73482/28411694
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "28411694"
{
"_rev": 28411694,
"_id": "73482/28411694",
"Hallo": "World"
}
</pre></div><p>Use a document handle and an etag:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET '-H if-none-match: "28542766"' --dump - http://localhost:8529/_api/document/73482/28542766
HTTP/1.1 304 Not Modified
content-type: text/plain;charset=utf-8
etag: "28542766"
</pre></div><p>Unknown document handle:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/document/73482/234567
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"errorMessage": "document /_api/document/73482/234567 not found",
"errorNum": 1202,
"code": 404,
"error": true
}
</pre></div> <p><a class="anchor" id="RestDocumentCreate"></a> <hr/>
<em>POST /_api/document</em> (creates a document)<hr/>
<br/>
<code><b>POST /_api/document?collection=<em>collection-identifier</em></b></code></p>
<p>Creates a new document in the collection identified by the <em>collection-identifier</em>. A JSON representation of the document must be passed as the body of the POST request.</p>
<p>If the document was created successfully, then a <code>HTTP 201</code> is returned and the "Location" header contains the path to the newly created document. The "ETag" header field contains the revision of the document.</p>
<p>The body of the response contains a JSON object with the same information. The attribute <code>_id</code> contains the document handle of the newly created document, the attribute <code>_rev</code> contains the document revision.</p>
<p>If the collection parameter <code>waitForSync</code> is <code>false</code>, then a <code>HTTP 202</code> is returned in order to indicate that the document has been accepted but not yet stored.</p>
<p>If the <em>collection-identifier</em> is unknown, then a <code>HTTP 404</code> is returned and the body of the response contains an error document.</p>
<p>If the body does not contain a valid JSON representation of an document, then a <code>HTTP 400</code> is returned and the body of the response contains an error document.</p>
<p><code><b>POST /_api/document?collection=<em>collection-name</em> &amp;createCollection=<em>create-flag</em></b></code></p>
<p>Instead of a <em>collection-identifier</em>, a <em>collection-name</em> can be used. If <em>create-flag</em> has a value of <code>true</code> or <code>yes</code>, then the collection is created if it does not yet exist. Other values for <em>create-flag</em> will be ignored so the collection must be present for the operation to succeed.</p>
<p><b>Examples</b><br/>
</p>
<p>Create a document given a collection identifier <code>161039</code> for the collection named <code>demo</code>. Note that the revision identifier might or might by equal to the last part of the document handle. It generally will be equal, but there is no guaranty.</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=73482
{ "Hallo" : "World" }
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
location: /_api/document/73482/26445614
etag: "26445614"
{
"_rev": 26445614,
"_id": "73482/26445614",
"error": false
}
</pre></div> <p>Create a document in a collection where <code>waitForSync</code> is <code>false</code>.</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=2957066
{ "Hallo" : "World" }
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
location: /_api/document/2957066/26576686
etag: "26576686"
{
"_rev": 26576686,
"_id": "2957066/26576686",
"error": false
}
</pre></div> <p>Create a document in a known, named collection</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=example
{ "Hallo" : "World" }
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
location: /_api/document/73482/26707758
etag: "26707758"
{
"_rev": 26707758,
"_id": "73482/26707758",
"error": false
}
</pre></div><p>Create a document in a new, named collection</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=example&amp;createCollection=true
{ "Hallo" : "World" }
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
location: /document/26838830/28280622
etag: "28280622"
{
"_rev": 28280622,
"_id": "26838830/28280622",
"error": false
}
</pre></div><p>Unknown collection identifier:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=123456
{}
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"errorMessage": "collection /_api/collection/123456 not found",
"errorNum": 1203,
"code": 404,
"error": true
}
</pre></div><p>Illegal document:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=73482
{ 1 : 2 }
HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
{
"errorMessage": "expecting attribute name",
"errorNum": 600,
"code": 400,
"error": true
}
</pre></div> <p><a class="anchor" id="RestDocumentReplace"></a> <hr/>
<em>PUT /_api/document</em> (updates a document)<hr/>
<br/>
<code><b>PUT /_api/document/<em>document-handle</em></b></code></p>
<p>Completely updates (i.e. replaces) the document identified by <em>document-handle</em>. If the document exists and can be updated, then a <code>HTTP 201</code> is returned and the "ETag" header field contains the new revision of the document.</p>
<p>If the new document passed in the body of the request contains the <em>document-handle</em> in the attribute <code>_id</code> and the revision in <code>_rev</code>, these attributes will be ignored. Only the URI and the "ETag" header are relevant in order to avoid confusion when using proxies.</p>
<p>The body of the response contains a JSON object with the information about the handle and the revision. The attribute <code>_id</code> contains the known <em>document-handle</em> of the updated document, the attribute <code>_rev</code> contains the new document revision.</p>
<p>If the document does not exist, then a <code>HTTP 404</code> is returned and the body of the response contains an error document.</p>
<p>If an etag is supplied in the "If-Match" header field, then the ArangoDB checks that the revision of the document is equal to the etag. If there is a mismatch, then a <code>HTTP 409</code> conflict is returned and no update is performed.</p>
<p><code><b>PUT /_api/document/<em>document-handle</em>?policy=<em>policy</em></b></code></p>
<p>As before, if <em>policy</em> is <code>error</code>. If <em>policy</em> is <code>last</code>, then the last write will win.</p>
<p><code><b>PUT /_api/document/<em>collection-identifier</em>/<em>document-identifier</em>?rev=<em>etag</em></b></code></p>
<p>You can also supply the etag using the parameter <code>rev</code> instead of an "ETag" header. You must never supply both the "ETag" header and the <code>rev</code> parameter.</p>
<p><b>Examples</b><br/>
</p>
<p>Using document handle:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/document/73482/29853486
{ "World" : "Hallo" }
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"_rev": 29919022,
"_id": "73482/29853486",
"error": false
}
</pre></div><p>Unknown document handle:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/document/73482/234567
{}
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"errorMessage": "document /_api/document/73482/234567 not found",
"errorNum": 1202,
"code": 404,
"error": true
}
</pre></div><p>Produce a revision conflict:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT '-H if-match: "30050093"' --dump - http://_api/localhost:8529/document/73482/30050094
{ "World" : "Hallo" }
HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
{
"_rev": 30050094,
"_id": "73482/30050094",
"error": true
}
</pre></div><p>Last write wins:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT '-H if-match: "30246701"' --dump - http://localhost:8529/_api/document/73482/30246702?policy=last
{ "World" : "Hallo" }
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"_rev": 30312238,
"_id": "73482/30246702",
"error": false
}
</pre></div><p>Alternative to header field:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/document/73482/30443310?rev=30443309
{ "World" : "Hallo" }
HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
{
"_rev": 30443310,
"_id": "73482/30443310",
"error": true
}
</pre></div> <p><a class="anchor" id="RestDocumentUpdate"></a> <hr/>
<em>PATCH /_api/document</em> (patches a document)<hr/>
<br/>
<code><b>PATCH /_api/document/<em>document-handle</em></b></code></p>
<p>Partially updates the document identified by <em>document-handle</em>. 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.</p>
<p>Setting an attribute value to <code>null</code> in the patch document will cause a value of <code>null</code> be saved for the attribute by default. If the intention is to delete existing attributes with the patch command, the URL parameter <code>keepNull</code> can be used with a value of <code>false</code>. 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 <code>null</code>.</p>
<p>The body of the response contains a JSON object with the information about the handle and the revision. The attribute <code>_id</code> contains the known <em>document-handle</em> of the updated document, the attribute <code>_rev</code> contains the new document revision.</p>
<p>If the document does not exist, then a <code>HTTP 404</code> is returned and the body of the response contains an error document.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PATCH --dump - http://localhost:8529/_api/document/73482/7229681
{ "hello": "world" }
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"_rev": 11916057,
"_id": "73482/7229681",
"error": false
}
&gt; curl --data @- -X PATCH --dump - http://localhost:8529/_api/document/73482/7229681
{ "numbers": { "one": 1, "two": 2, "three": 3, "empty": null } }
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"_rev": 12309273,
"_id": "73482/7229681",
"error": false
}
&gt; curl -X GET --dump - http://localhost:8529/_api/document/73482/7229681
{ "numbers": { "one": 1, "two": 2, "three": 3, "empty": null } }
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"hello": "world",
"numbers": {
"empty": null,
"one": 1,
"two": 2,
"three": 3
},
"_rev": 12309273,
"_id": "73482/7229681"
}
&gt; curl --data @- -X PATCH --dump - http://localhost:8529/_api/document/73482/7229681?keepNull=false
{ "hello": null, "numbers": { "four": 4 } }
{
"_rev": 12571417,
"_id": "73482/7229681",
"error": false
}
&gt; curl -X GET --dump - http://localhost:8529/_api/document/73482/7229681
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"numbers": {
"empty": null,
"one": 1,
"two": 2,
"three": 3,
"four": 4,
},
"_rev": 12571417,
"_id": "73482/7229681"
}
</pre></div> <p><a class="anchor" id="RestDocumentDelete"></a> <hr/>
<em>DELETE /_api/document</em> (deletes a document)<hr/>
<br/>
<code><b>DELETE /_api/document/<em>document-handle</em></b></code></p>
<p>Deletes the document identified by <em>document-handle</em>. If the document exists and could be deleted, then a <code>HTTP 204</code> is returned.</p>
<p>The body of the response contains a JSON object with the information about the handle and the revision. The attribute <code>_id</code> contains the known <em>document-handle</em> of the updated document, the attribute <code>_rev</code> contains the known document revision.</p>
<p>If the document does not exist, then a <code>HTTP 404</code> is returned and the body of the response contains an error document.</p>
<p>If an etag is supplied in the "If-Match" field, then the ArangoDB checks that the revision of the document is equal to the etag. If there is a mismatch, then a <code>HTTP 412</code> conflict is returned and no delete is performed.</p>
<p><code><b>DELETE /_api/document/<em>document-handle</em>?policy=<em>policy</em></b></code></p>
<p>As before, if <em>policy</em> is <code>error</code>. If <em>policy</em> is <code>last</code>, then the last write will win.</p>
<p><code><b>DELETE /_api/document/<em>document-handle</em>?rev=<em>etag</em></b></code></p>
<p>You can also supply the etag using the parameter <code>rev</code> instead of an "If-Match" header. You must never supply both the "If-Match" header and the <code>rev</code> parameter.</p>
<p><b>Examples</b><br/>
</p>
<p>Using document handle:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X DELETE --dump - http://localhost:8529/_api/document/73482/30967598
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"_rev": 30967598,
"_id": "73482/30967598",
"error": false
}
</pre></div><p>Unknown document handle:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X DELETE --dump - http://localhost:8529/_api/document/73482/234567
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"errorMessage": "document /_api/document/73482/234567 not found",
"errorNum": 1202,
"code": 404,
"error": true
}
</pre></div><p>Revision conflict:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X DELETE '-H if-match: "31098669"' --dump - http://localhost:8529/_api/document/73482/31098670
HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
{
"_rev": 31098670,
"_id": "73482/31098670",
"error": true
}
</pre></div> <p><a class="anchor" id="RestDocumentHead"></a> <hr/>
<em>HEAD /_api/document</em> (reads a document header)<hr/>
<br/>
<code><b>HEAD /_api/document/<em>document-handle</em></b></code></p>
<p>Like <code>GET</code>, 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.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl -X HEAD --dump - http://localhost:8529/_api/document/73482/29591342
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "29591342"
</pre></div> <p><a class="anchor" id="RestDocumentReadAll"></a> <hr/>
<em>GET /_api/document</em> (reads all document)<hr/>
<br/>
<code><b>GET /_api/document?collection=<em>collection-identifier</em></b></code></p>
<p>Returns a list of all URI for all documents from the collection identified by <em>collection-identifier</em>.</p>
<p>Instead of a <em>collection-identifier</em>, a collection name can be given.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/document?collection=6627082
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"documents": [
"/document/6627082/29198126",
"/document/6627082/29329198",
"/document/6627082/29263662"
]
}
</pre></div> </div></div>
</div></body></html>
Reference in New Issue View Git Blame Copy Permalink