arangodb/js/apps/system/aardvark/api-docs/transaction.json

{
    "basePath": "/",
    "swaggerVersion": "1.1",
    "apiVersion": "0.1",
    "apis": [
        {
            "operations": [
                {
                    "errorResponses": [
                        {
                            "reason": "If the transaction is fully executed and committed on the server, <em>HTTP 200</em> will be returned. <br><br>",
                            "code": "200"
                        },
                        {
                            "reason": "If the transaction specification is either missing or malformed, the server will respond with <em>HTTP 400</em>. <br><br>",
                            "code": "400"
                        },
                        {
                            "reason": "If the transaction specification contains an unknown collection, the server will respond with <em>HTTP 404</em>. <br><br>",
                            "code": "404"
                        },
                        {
                            "reason": "Exceptions thrown by users will make the server respond with a return code of <em>HTTP 500</em> <br><br>",
                            "code": "500"
                        }
                    ],
                    "parameters": [
                        {
                            "dataType": "String",
                            "paramType": "body",
                            "required": "true",
                            "name": "body",
                            "description": "Contains the <em>collections</em> and <em>action</em>. <br><br>"
                        }
                    ],
                    "notes": "<br><br> The transaction description must be passed in the body of the POST request. <br><br> The following attributes must be specified inside the JSON object: <br><br>  <ul class=\"swagger-list\"><li><em>collections</em>: contains the list of collections to be used in the transaction (mandatory). <em>collections</em> must be a JSON array that can have the optional sub-attributes <em>read</em> and <em>write</em>. <em>read</em> and <em>write</em> must each be either lists of collections names or strings with a single collection name.  <li><em>action</em>: the actual transaction operations to be executed, in the form of stringified Javascript code. The code will be executed on server side, with late binding. It is thus critical that the code specified in <em>action</em> properly sets up all the variables it needs. If the code specified in <em>action</em> ends with a return statement, the value returned will also be returned by the REST API in the <em>result</em> attribute if the transaction committed successfully.  </ul> The following optional attributes may also be specified in the request: <br><br>  <ul class=\"swagger-list\"><li><em>waitForSync</em>: an optional boolean flag that, if set, will force the transaction to write all data to disk before returning.  <li><em>lockTimeout</em>: an optional numeric value that can be used to set a timeout for waiting on collection locks. If not specified, a default value will be used. Setting <em>lockTimeout</em> to <em>0</em> will make ArangoDB not time out waiting for a lock.  <li><em>params</em>: optional arguments passed to <em>action</em>.  </ul> If the transaction is fully executed and committed on the server, <em>HTTP 200</em> will be returned. Additionally, the return value of the code defined in <em>action</em> will be returned in the <em>result</em> attribute. <br><br> For successfully committed transactions, the returned JSON object has the following properties: <br><br>  <ul class=\"swagger-list\"><li><em>error</em>: boolean flag to indicate if an error occurred (<em>false</em> in this case)  <li><em>code</em>: the HTTP status code  <li><em>result</em>: the return value of the transaction  </ul> If the transaction specification is either missing or malformed, the server will respond with <em>HTTP 400</em>. <br><br> The body of the response will then contain a JSON object with additional error details. The object has the following attributes: <br><br>  <ul class=\"swagger-list\"><li><em>error</em>: boolean flag to indicate that an error occurred (<em>true</em> in this case)  <li><em>code</em>: the HTTP status code  <li><em>errorNum</em>: the server error number  <li><em>errorMessage</em>: a descriptive error message  </ul> If a transaction fails to commit, either by an exception thrown in the <em>action</em> code, or by an internal error, the server will respond with an error. Any other errors will be returned with any of the return codes <em>HTTP 400</em>, <em>HTTP 409</em>, or <em>HTTP 500</em>. <br><br>",
                    "summary": " Execute transaction",
                    "httpMethod": "POST",
                    "examples": "<br><br> Executing a transaction on a single collection: <br><br><br><br><pre><code class=\"json\">shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction\n{ \n  \"collections\" : { \n    \"write\" : \"products\" \n  }, \n  \"action\" : \"function () { var db = require('internal').db; db.products.save({});  return db.products.count(); }\" \n}\n\nHTTP/1.1 200 OK\ncontent-type: application/json; charset=utf-8\n\n{ \n  \"result\" : 1, \n  \"error\" : false, \n  \"code\" : 200 \n}\n</code></pre><br><br><br> Executing a transaction using multiple collections: <br><br><br><br><pre><code class=\"json\">shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction\n{ \n  \"collections\" : { \n    \"write\" : [ \n      \"products\", \n      \"materials\" \n    ] \n  }, \n  \"action\" : \"function () {var db = require('internal').db;db.products.save({});db.materials.save({});return 'worked!';}\" \n}\n\nHTTP/1.1 200 OK\ncontent-type: application/json; charset=utf-8\n\n{ \n  \"result\" : \"worked!\", \n  \"error\" : false, \n  \"code\" : 200 \n}\n</code></pre><br><br><br> Aborting a transaction due to an internal error: <br><br><br><br><pre><code class=\"json\">shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction\n{ \n  \"collections\" : { \n    \"write\" : \"products\" \n  }, \n  \"action\" : \"function () {var db = require('internal').db;db.products.save({ _key: 'abc'});db.products.save({ _key: 'abc'});}\" \n}\n\nHTTP/1.1 400 Bad Request\ncontent-type: application/json; charset=utf-8\n\n{ \n  \"error\" : true, \n  \"code\" : 400, \n  \"errorNum\" : 1210, \n  \"errorMessage\" : \"Error: unique constraint violated\\n  at eval (<anonymous>:2:99)\\n  at eval (<anonymous>:2:122)\\n  at post_api_transaction (js/actions/api-transaction.js:268:16)\\n  at Function.actions.defineHttp.callback (js/actions/api-transaction.js:288:11)\\n\" \n}\n</code></pre><br><br><br> Aborting a transaction by explicitly throwing an exception: <br><br><br><br><pre><code class=\"json\">shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction\n{ \n  \"collections\" : { \n    \"read\" : \"products\" \n  }, \n  \"action\" : \"function () { throw 'doh!'; }\" \n}\n\nHTTP/1.1 500 Internal Error\ncontent-type: application/json; charset=utf-8\n\n{ \n  \"error\" : true, \n  \"code\" : 500, \n  \"errorNum\" : 500, \n  \"errorMessage\" : \"doh!\" \n}\n</code></pre><br><br><br> Referring to a non-existing collection: <br><br><br><br><pre><code class=\"json\">shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction\n{ \n  \"collections\" : { \n    \"read\" : \"products\" \n  }, \n  \"action\" : \"function () { return true; }\" \n}\n\nHTTP/1.1 404 Not Found\ncontent-type: application/json; charset=utf-8\n\n{ \n  \"error\" : true, \n  \"code\" : 404, \n  \"errorNum\" : 1203, \n  \"errorMessage\" : \"Error: collection not found\\n  at post_api_transaction (js/actions/api-transaction.js:268:16)\\n  at Function.actions.defineHttp.callback (js/actions/api-transaction.js:288:11)\\n\" \n}\n</code></pre><br><br><br>",
                    "nickname": "ExecuteTransaction"
                }
            ],
            "path": "/_api/transaction"
        }
    ]
}