HTTP interface for JavaScript Transactions

The HTTP API for JavaScript Transactions lets you run a transaction that leverages ArangoDB’s JavaScript API by submitting a single HTTP request

JavaScript Transactions are executed on the server. Transactions can be initiated by clients by sending the transaction description for execution to the server.

JavaScript Transactions in ArangoDB do not offer separate BEGIN, COMMIT and ROLLBACK operations. Instead, JavaScript Transactions are described by a JavaScript function, and the code inside the JavaScript function is then be executed transactionally.

At the end of the function, the transaction is automatically committed, and all changes done by the transaction are persisted. If an exception is thrown during transaction execution, all operations performed in the transaction are rolled back.

For a more detailed description of how transactions work in ArangoDB please refer to Transactions.

Execute transaction

execute a server-side transaction

POST /_api/transaction

Request Body

collections (string, required): collections must be a JSON object that can have one or all sub-attributes read, write or exclusive, each being an array of collection names or a single collection name as string. Collections that will be written to in the transaction must be declared with the write or exclusive attribute or it will fail, whereas non-declared collections from which is solely read will be added lazily. The optional sub-attribute allowImplicit can be set to false to let transactions fail in case of undeclared collections for reading. Collections for reading should be fully declared if possible, to avoid deadlocks.
action (string, required): 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 action properly sets up all the variables it needs. If the code specified in action ends with a return statement, the value returned will also be returned by the REST API in the result attribute if the transaction committed successfully.
waitForSync (boolean, optional): an optional boolean flag that, if set, will force the transaction to write all data to disk before returning.
allowImplicit (boolean, optional): Allow reading from undeclared collections.
lockTimeout (integer, optional): an optional numeric value that can be used to set a timeout in seconds for waiting on collection locks. This option is only meaningful when using exclusive locks. If not specified, a default value of 900 seconds will be used. Setting lockTimeout to 0 will make ArangoDB not time out waiting for a lock.
params (string, optional): optional arguments passed to action.
maxTransactionSize (integer, optional): Transaction size limit in bytes.

The transaction description must be passed in the body of the POST request.

If the transaction is fully executed and committed on the server, HTTP 200 will be returned. Additionally, the return value of the code defined in action will be returned in the result attribute.

For successfully committed transactions, the returned JSON object has the following properties:

error: boolean flag to indicate if an error occurred (false in this case)
code: the HTTP status code
result: the return value of the transaction

If the transaction specification is either missing or malformed, the server will respond with HTTP 400.

The body of the response will then contain a JSON object with additional error details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)
code: the HTTP status code
errorNum: the server error number
errorMessage: a descriptive error message

If a transaction fails to commit, either by an exception thrown in the action 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 HTTP 400, HTTP 409, or HTTP 500.

Responses

HTTP 200: If the transaction is fully executed and committed on the server, HTTP 200 will be returned.

HTTP 400: If the transaction specification is either missing or malformed, the server will respond with HTTP 400.

HTTP 404: If the transaction specification contains an unknown collection, the server will respond with HTTP 404.

HTTP 500: Exceptions thrown by users will make the server respond with a return code of HTTP 500

Examples

Executing a transaction on a single collection

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "write" : "products" 
  }, 
  "action" : "function () { var db = require('@arangodb').db; db.products.save({});  return db.products.count(); }" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 37
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : 1 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "write" : "products" 
  }, 
  "action" : "function () { var db = require('@arangodb').db; db.products.save({});  return db.products.count(); }" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 37
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Executing a transaction using multiple collections

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "write" : [ 
      "products", 
      "materials" 
    ] 
  }, 
  "action" : "function () {var db = require('@arangodb').db;db.products.save({});db.materials.save({});return 'worked!';}" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 45
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : "worked!" 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "write" : [ 
      "products", 
      "materials" 
    ] 
  }, 
  "action" : "function () {var db = require('@arangodb').db;db.products.save({});db.materials.save({});return 'worked!';}" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 45
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Aborting a transaction due to an internal error

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "write" : "products" 
  }, 
  "action" : "function () {var db = require('@arangodb').db;db.products.save({ _key: 'abc'});db.products.save({ _key: 'abc'});}" 
}
EOF

HTTP/1.1 409 Conflict
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 154
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 409, 
  "error" : true, 
  "errorMessage" : "unique constraint violated - in index primary of type primary over '_key'; conflicting key: abc", 
  "errorNum" : 1210 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "write" : "products" 
  }, 
  "action" : "function () {var db = require('@arangodb').db;db.products.save({ _key: 'abc'});db.products.save({ _key: 'abc'});}" 
}
EOF

HTTP/1.1 409 Conflict
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 154
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Aborting a transaction by explicitly throwing an exception

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "read" : "products" 
  }, 
  "action" : "function () { throw 'doh!'; }" 
}
EOF

HTTP/1.1 500 Internal Server Error
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 63
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 500, 
  "error" : true, 
  "errorMessage" : "doh!", 
  "errorNum" : 1650 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "read" : "products" 
  }, 
  "action" : "function () { throw 'doh!'; }" 
}
EOF

HTTP/1.1 500 Internal Server Error
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 63
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Referring to a non-existing collection

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "read" : "products" 
  }, 
  "action" : "function () { return true; }" 
}
EOF

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "collection or view not found: products", 
  "errorNum" : 1203 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{ 
  "collections" : { 
    "read" : "products" 
  }, 
  "action" : "function () { return true; }" 
}
EOF

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

❮ Stream Transactions Indexes ❯