doc: Add RPC interface guidelines #10281

pull laanwj wants to merge 1 commits into bitcoin:master from laanwj:2017_04_rpc_if_guidelines changing 1 files +73 −0

laanwj commented at 5:23 AM on April 26, 2017: member

Could be useful. Anything that I forgot?
laanwj added the label Docs and Output on Apr 26, 2017
laanwj added the label RPC/REST/ZMQ on Apr 26, 2017
in doc/developer-notes.md:545 in 32fd23f50f outdated
```
 540 | +
 541 | +  - *Rationale*: This is impossible to use with `bitcoin-cli`, and can be surprising to users.
 542 | +
 543 | +  - *Exception*: Some RPC calls can take both an `int` and `bool`, most notably when a bool was switched
 544 | +    to a multi-value, or due to other historical reasons. **Always** have false map to 0 and
 545 | +    true to 1 in this case.
```
kallewoof commented at 6:42 AM on April 26, 2017:

This is not the case right now. At the moment, 0 maps to false and !0 maps to true. See e.g. getrawtransaction's verbose argument handling.

laanwj commented at 7:17 AM on April 26, 2017:

EH, I have that the wrong way around, thanks.
laanwj commented at 7:20 AM on April 26, 2017:

Or not. What I meant here is:

false=0 true=1

E.g, the C++ mapping, not the bash mapping. As far as I know, we follow that everywhere? If this wording is confusing, can you suggest another way.
kallewoof commented at 7:40 AM on April 26, 2017:

I read it as "interpret 0 as false and 1 as true, and anything else is [??]".

I.e. if a user passes 2 or -1 to the new RPC command which maps as you said, how will it treat values beyond [0, 1]?

Am I misunderstanding?

laanwj commented at 8:07 AM on April 26, 2017:

I don't say anything about values besides 0 and 1 on purpose. Those may either map to 1, or to something else entirely (referring to "when bool has switched to multi-value"), or cause a failure.

kallewoof commented at 8:26 AM on April 26, 2017:

Ohh I was reading this backwards. You're talking about when a bool becomes an int, and I about when an int is interpreted as a bool. I'll think on wording to make this obvious.

kallewoof commented at 7:41 AM on May 1, 2017:

Re-reading this, I think I was simply not reading it properly. I think it looks fine as is.

in doc/developer-notes.md:553 in 32fd23f50f outdated

 548 | +
 549 | +  - *Rationale*: If not, the call can not be used with name-based arguments.
 550 | +
 551 | +- Set okSafeMode in the RPC command table to a sensible value: safe mode is when the
 552 | +  block chain is regarded to be in a confused state, and the client deems it unsafe to
 553 | +  do anything irreversible such as send. Anything that just queries should be permitted.

kallewoof commented at 6:43 AM on April 26, 2017:

Thanks for this! I vaguely presumed this was the case but never found anything explicitly stating it.

kallewoof commented at 6:44 AM on April 26, 2017: member

Nice.
jonasschnelli commented at 6:46 AM on April 26, 2017: contributor

Great addition. Concept ACK.

in doc/developer-notes.md:552 in 32fd23f50f outdated

 547 | +- Don't forget to fill in the argument names correctly in the RPC command table.
 548 | +
 549 | +  - *Rationale*: If not, the call can not be used with name-based arguments.
 550 | +
 551 | +- Set okSafeMode in the RPC command table to a sensible value: safe mode is when the
 552 | +  block chain is regarded to be in a confused state, and the client deems it unsafe to

fanquake commented at 6:47 AM on April 26, 2017:

nit: s/block chain/blockchain

laanwj force-pushed on Apr 26, 2017
jnewbery commented at 9:13 PM on May 1, 2017: member

Looks good. ACK 359f71d0fb243fa49884132c0fb0c24118d77842
sipa commented at 10:52 PM on May 1, 2017: member

ACK
doc: Add RPC interface guidelines c26655ed3f
laanwj force-pushed on May 2, 2017
laanwj merged this on May 2, 2017
laanwj closed this on May 2, 2017
laanwj referenced this in commit 0e8499c53f on May 2, 2017
PastaPastaPasta referenced this in commit 0ba8e2c784 on Jun 10, 2019
PastaPastaPasta referenced this in commit 0ef8b01621 on Jun 10, 2019
PastaPastaPasta referenced this in commit 9378ae7885 on Jun 11, 2019
PastaPastaPasta referenced this in commit 963b9df247 on Jun 11, 2019
PastaPastaPasta referenced this in commit 2409edd1bb on Jun 12, 2019
PastaPastaPasta referenced this in commit 8d656e9001 on Jun 14, 2019
PastaPastaPasta referenced this in commit 67548e9524 on Jun 14, 2019
PastaPastaPasta referenced this in commit 3a0fea1840 on Jun 14, 2019
PastaPastaPasta referenced this in commit f097b2d94d on Jun 14, 2019
PastaPastaPasta referenced this in commit eb79ffaf4b on Jun 15, 2019
PastaPastaPasta referenced this in commit 9ec60545b2 on Jun 19, 2019
barrystyle referenced this in commit 7365340d83 on Jan 22, 2020
MarcoFalke locked this on Sep 8, 2021

Contributors

Labels