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)
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:
For the Python driver:
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:
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
, andsync_transaction
. By removing the default, we force the developer to make a conscious choice when coding. In the tutorials and examples we can usecommit_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.