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

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.