From e366ec2da38a77d1acde752ffa7e51a2a5a6c9da Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Sat, 13 Apr 2013 00:51:02 +0200 Subject: [PATCH] added documentation for transaction REST API --- Documentation/Examples/api-transaction-abort | 7 ++++ .../Examples/api-transaction-abort-internal | 7 ++++ Documentation/Examples/api-transaction-multi | 7 ++++ Documentation/Examples/api-transaction-single | 7 ++++ .../ImplementorManual/HttpTransactions.md | 31 +++++++++++++++++ .../ImplementorManual/HttpTransactionsTOC.md | 7 ++++ Documentation/Makefile.files | 3 ++ js/actions/api-cursor.js | 1 + js/actions/api-transaction.js | 34 +++++++++++++++++-- 9 files changed, 101 insertions(+), 3 deletions(-) create mode 100644 Documentation/Examples/api-transaction-abort create mode 100644 Documentation/Examples/api-transaction-abort-internal create mode 100644 Documentation/Examples/api-transaction-multi create mode 100644 Documentation/Examples/api-transaction-single create mode 100644 Documentation/ImplementorManual/HttpTransactions.md create mode 100644 Documentation/ImplementorManual/HttpTransactionsTOC.md diff --git a/Documentation/Examples/api-transaction-abort b/Documentation/Examples/api-transaction-abort new file mode 100644 index 0000000000..0ac8fe340f --- /dev/null +++ b/Documentation/Examples/api-transaction-abort @@ -0,0 +1,7 @@ +> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction +{ "collections" : { "read" : "users" }, "action" : "throw \"doh!\";" } + +HTTP/1.1 500 Internal Error +content-type: application/json; charset=utf-8 + +{ "error" : true, "code" : 500, "errorNum" : 500, "errorMessage" : "doh!" } diff --git a/Documentation/Examples/api-transaction-abort-internal b/Documentation/Examples/api-transaction-abort-internal new file mode 100644 index 0000000000..d81eb1ca81 --- /dev/null +++ b/Documentation/Examples/api-transaction-abort-internal @@ -0,0 +1,7 @@ +> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction +{ "collections" : { "write" : [ "users" ] }, "action" : "var users = require(\"internal\").db.users; users.save({ _key: \"abc\" }); users.save({ _key: \"abc\" });" } + +HTTP/1.1 400 Bad Request +content-type: application/json; charset=utf-8 + +{ "error" : true, "code" : 400, "errorNum" : 1210, "errorMessage" : "cannot save document: unique constraint violated" } diff --git a/Documentation/Examples/api-transaction-multi b/Documentation/Examples/api-transaction-multi new file mode 100644 index 0000000000..ff5c505ff6 --- /dev/null +++ b/Documentation/Examples/api-transaction-multi @@ -0,0 +1,7 @@ +> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction +{ "collections" : { "write" : [ "users", "logins" ] }, "action" : "var users = require(\"internal\").db.users; var logins = require(\"internal\").db.logins; users.save({ }); logins.save({ }); return \"worked!\";" } + +HTTP/1.1 200 OK +content-type: application/json; charset=utf-8 + +{ "result" : "worked!", "error" : false, "code" : 200 } diff --git a/Documentation/Examples/api-transaction-single b/Documentation/Examples/api-transaction-single new file mode 100644 index 0000000000..7a3a0ac20e --- /dev/null +++ b/Documentation/Examples/api-transaction-single @@ -0,0 +1,7 @@ +> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction +{ "collections" : { "write" : "users" }, "action" : "var users = require(\"internal\").db.users; users.save({ _key: \"hello\" }); return users.count();" } + +HTTP/1.1 200 OK +content-type: application/json; charset=utf-8 + +{ "result" : 1, "error" : false, "code" : 200 } diff --git a/Documentation/ImplementorManual/HttpTransactions.md b/Documentation/ImplementorManual/HttpTransactions.md new file mode 100644 index 0000000000..5bcf3d334c --- /dev/null +++ b/Documentation/ImplementorManual/HttpTransactions.md @@ -0,0 +1,31 @@ +HTTP Interface for Transactions {#HttpTransactions} +=================================================== + +@NAVIGATE_HttpTransactions +@EMBEDTOC{HttpTransactionsTOC} + +Transactions {#HttpTransactionsIntro} +===================================== + +ArangoDB's transactions are executed on the server. Transactions can be +initiated by clients by sending the transaction description for execution to +the server. + +Transactions in ArangoDB do not offer seperate `BEGIN`, `COMMIT` and `ROLLBACK` +operations as they are available in many other database products. +Instead, ArangoDB transactions are described by a Javascript function, and the +code inside the Javascript function will then be executed transactionally. +At the end of the function, the transaction is automatically committed, and all +changes done by the transaction will be 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 @ref Transactions. + +Executing Transactions via HTTP {#HttpTransactionsHttp} +======================================================= + +@anchor HttpTransactionsPost +@copydetails JSF_POST_api_transaction + diff --git a/Documentation/ImplementorManual/HttpTransactionsTOC.md b/Documentation/ImplementorManual/HttpTransactionsTOC.md new file mode 100644 index 0000000000..785eeef1aa --- /dev/null +++ b/Documentation/ImplementorManual/HttpTransactionsTOC.md @@ -0,0 +1,7 @@ +TOC {#HttpTransactionsTOC} +========================== + +- @ref HttpTransactions + - @ref HttpTransactionsIntro + - @ref HttpTransactionsHttp + - @ref HttpTransactionsPost "POST /_api/transactions" diff --git a/Documentation/Makefile.files b/Documentation/Makefile.files index 3b242f4f0d..6b26360670 100644 --- a/Documentation/Makefile.files +++ b/Documentation/Makefile.files @@ -37,11 +37,13 @@ DOXYGEN = \ Doxygen/js/actions/api-cursor.c \ Doxygen/js/actions/api-edges.c \ Doxygen/js/actions/api-explain.c \ + Doxygen/js/actions/api-foxx.c \ Doxygen/js/actions/api-graph.c \ Doxygen/js/actions/api-index.c \ Doxygen/js/actions/api-query.c \ Doxygen/js/actions/api-simple.c \ Doxygen/js/actions/api-system.c \ + Doxygen/js/actions/api-transaction.c \ Doxygen/js/actions/api-user.c \ Doxygen/js/common/bootstrap/module-console.c \ Doxygen/js/common/bootstrap/module-fs.c \ @@ -93,6 +95,7 @@ WIKI = \ HttpQuery \ HttpSimple \ HttpSystem \ + HttpTransactions \ HttpUser \ ImpManual \ ImpManualBasics \ diff --git a/js/actions/api-cursor.js b/js/actions/api-cursor.js index 3c8655595a..1fced99540 100644 --- a/js/actions/api-cursor.js +++ b/js/actions/api-cursor.js @@ -135,6 +135,7 @@ function POST_api_cursor(req, res) { var json = actions.getJsonBody(req, res); if (json === undefined) { + actions.resultBad(req, res, arangodb.ERROR_QUERY_EMPTY); return; } diff --git a/js/actions/api-transaction.js b/js/actions/api-transaction.js index d7a481fa15..fa04e344ec 100644 --- a/js/actions/api-transaction.js +++ b/js/actions/api-transaction.js @@ -25,6 +25,7 @@ /// @author Copyright 2012, triAGENS GmbH, Cologne, Germany //////////////////////////////////////////////////////////////////////////////// +var arangodb = require("org/arangodb"); var actions = require("org/arangodb/actions"); // ----------------------------------------------------------------------------- @@ -58,8 +59,8 @@ var actions = require("org/arangodb/actions"); /// /// - @LIT{lockTimeout}: 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 @LIT{lockTimeout} to 0 will make ArangoDB not -/// time out waiting for a lock. +/// value will be used. Setting @LIT{lockTimeout} to @LIT{0} will make ArangoDB +/// not time out waiting for a lock. /// /// - @LIT{action}: the actual transaction operations to be executed, in the /// form of stringified Javascript code. The code will be executed on server @@ -98,12 +99,39 @@ var actions = require("org/arangodb/actions"); /// /// If a transaction fails to commit, either by an exception thrown in the /// @LIT{action} code, or by an internal error, the server will respond with -/// @LIT{HTTP 500}. +/// an error. +/// +/// Exceptions thrown by users will make the server respond with a return code of +/// @LIT{HTTP 500}. Any other errors will be returned with any of the return codes +/// @LIT{HTTP 400}, @LIT{HTTP 409}, or @LIT{HTTP 500}. +/// +/// @EXAMPLES +/// +/// Executing a transaction on a single collection: +/// +/// @verbinclude api-transaction-single +/// +/// Executing a transaction using multiple collections: +/// +/// @verbinclude api-transaction-multi +/// +/// Aborting a transaction due to an internal error: +/// +/// @verbinclude api-transaction-abort-internal +/// +/// Aborting a transaction by throwing an exception: +/// +/// @verbinclude api-transaction-abort //////////////////////////////////////////////////////////////////////////////// function POST_api_transaction(req, res) { var json = actions.getJsonBody(req, res); + if (json === undefined) { + actions.resultBad(req, res, arangodb.ERROR_HTTP_BAD_PARAMETER); + return; + } + var result = TRANSACTION(json); actions.resultOk(req, res, actions.HTTP_OK, { "result" : result });