bigchaindb: Problem: Unsure if default POST /transactions mode should be 'async' or 'commit'

In BigchainDB 1.3 and before, the POST /transactions endpoint (to post a new transaction to a BigchainDB node), didn’t have any query parameters.

As of BigchainDB 2.0, there are three possible query parameters: /transactions?mode=async, /transactions?mode=sync and /transactions?mode=commit.

Currently, if no query parameter is included in the HTTP request, then mode is assumed to be async, i.e. the de facto default in the HTTP API is async.

The original reasoning for that was that mode=async means the same as having no query parameter always meant, i.e. you get back a 202 ACCEPTED response if the initial node thought the transaction was valid, even if the transaction subsequently got lost or rejected by the network.

However, in the Python driver, the default mode is currently assumed to be commit. The reasoning there is that the user doesn’t have to think too much. If they get back a 200-level response, then they can rest assured that their transaction got accepted and committed into a block. And if it was invalid or rejected, they find out why. In other words, commit is more user-friendly.

What should the default mode be, async or commit?

About this issue

  • Original URL
  • State: closed
  • Created 6 years ago
  • Comments: 16 (13 by maintainers)

Most upvoted comments

I discussed this with @codegeschrei and @manolodewiner this morning and here is what we decided to do:

For both drivers (Python and JavaScript), have four methods, with the one that doesn’t specify the mode doing the same as the one that uses “commit” (because “commit” it a better user experience).

For the JavaScript driver:

postTransaction()  // does the same as postTransactionCommit()
postTransactionAsync()   // new method
postTransactionSync()
postTransactionCommit()

For the Python driver:

send() # with no optional mode=something parameter, always does commit
send_async()     # new method
send_sync()      # new method
send_commit()    # new method

Actually, the send() method might keep its optional mode=something parameter, but if it’s not specified the default must be commit.

@codegeschrei @manolodewiner I think we could:

  • leave the three-function solution as-is in the JavaScript driver (i.e. where the default is async, as it has always been)
  • change the Python driver to have a required second parameter (mode) with no default. This will break existing code, so we should raise a helpful exception that tells them what to do to fix it; at that point we can recommend that they set the mode to ‘commit’.

An alternative would be for drivers to require the mode parameter to be set explicitly when posting a new transaction (i.e. have no default value). Driver users would be forced to think about the mode. We could recommend that they use commit.

I agree with @ttmc, the idea is to deprecate the current one POST /transactions?mode=... and have two (three?) different API endpoints:

  • POST /commit/transaction
  • POST /async/transaction
  • POST /sync/transaction

This change is reflected by both Python and JavaScript drivers by adding the methods commit_transaction, async_transaction, and sync_transaction. By removing the default, we force the developer to make a conscious choice when coding. In the tutorials and examples we can use commit_transaction always.

I would agree with @codegeschrei that the default mode should be commit as the developers who are getting started with the code examples and implementation should be able to see the transaction response in real time.