/bitcoin.org

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Polish and expand Bitcoin Core RPC interface intro in developer reference #1030

Merged
merged 3 commits into from Sep 4, 2015

Conversation

Reviewers
No reviews
Assignees
No one assigned
Labels
Dev Docs Merge Scheduled
Projects
None yet
Milestone
No milestone
3 participants
@carnesen @harding @saivann
@carnesen
Contributor

carnesen commented Aug 26, 2015

This PR contains a polished and expanded version of the developer reference section that describes the Bitcoin Core RPC interface. Site tests are passing on my laptop and on Travis CI. A preview of the changes can be found here:

http://bitcoin-dot-org.carnesen.com/en/developer-reference#remote-procedure-calls-rpcs

For comparison here's that section on the site currently:

https://bitcoin.org/en/developer-reference#remote-procedure-calls-rpcs

The changes in this PR are limited to the RPC interface description up to where the "Quick Reference" starts.

Feedback is welcomed, and I'd be happy to explain why I made any of these changes, just let me know.

@harding harding and 1 other commented on an outdated diff Aug 26, 2015

_includes/ref/bitcoin-core/rpcs/intro.md
-In order to start `bitcoind`, you will need to set a password for
-JSON-RPC in the `bitcoin.conf` file. See the [Examples
-Page][devexamples] for details. JSON-RPC starts on port 8332 for mainnet
-and 18332 for testnet and regtest. By default, `bitcoind` doesn't use a
-JSON-RPC user, but you can set one (see `bitcoind --help`).
-
-The interface is not intended for public access and is only accessible
-from localhost by default.
-
-RPCs are made using the standard JSON-RPC 1.0 syntax, which sends several
-standard arguments:
+Bitcoin Core provides a remote procedure call (RPC) interface for various
+administrative tasks, wallet operations, and queries about network and block
+chain data.
+
+If you start Bitcoin Core using `bitcoin-xt`, the RPC interface is disabled by
@harding

harding Aug 26, 2015

Contributor

Did you mean to say bitcoin-qt here?

@carnesen

carnesen Aug 26, 2015

Contributor

Indeed I did. Good eye. What a difference a letter makes :) I've fixed this locally on my laptop. Unless somebody tells me otherwise, I'll bundle all these feedback-inspired changes into a single commit.

@harding

harding Aug 26, 2015

Contributor

Bundling is good.

@harding harding and 1 other commented on an outdated diff Aug 26, 2015

_includes/ref/bitcoin-core/rpcs/intro.md
-
-The interface is not intended for public access and is only accessible
-from localhost by default.
-
-RPCs are made using the standard JSON-RPC 1.0 syntax, which sends several
-standard arguments:
+Bitcoin Core provides a remote procedure call (RPC) interface for various
+administrative tasks, wallet operations, and queries about network and block
+chain data.
+
+If you start Bitcoin Core using `bitcoin-xt`, the RPC interface is disabled by
+default. To enable it, set `server=1` in `bitcoin.conf` or supply the `-server`
+argument when invoking the program.
+
+If you start Bitcoin Core using `bitcoind`, the RPC interface is enabled by
+default. To disable it, set `server=0` in `bitcoin.conf`.
@harding

harding Aug 26, 2015

Contributor

Does using bitcoind without server=1 make sense? If you do that, there's no way to see what it's doing or to stop it using the stop command. (It should stop safely if killed using the right signal, but that seems like something most people would want to avoid.)

@carnesen

carnesen Aug 26, 2015

Contributor

I couldn't think of a good use case for bitcoind + server=0. I'll remove the sentence.

@harding harding and 1 other commented on an outdated diff Aug 26, 2015

_includes/ref/bitcoin-core/rpcs/intro.md
+(CLI) to Bitcoin Core or for making RPC calls from applications written in
+languages lacking a suitable native client. The remainder of this section
+describes the Bitcoin Core RPC protocol in detail.
+
+The Bitcoin Core RPC service listens for HTTP `POST` requests on port 8332 in
+mainnet mode or 18332 in testnet or regtest mode. The port number can be changed
+by setting `rpcport` in `bitcoin.conf`. By default the RPC service binds to your
+server's [localhost](https://en.wikipedia.org/wiki/Localhost) loopback
+network<!--noref--> interface so it's not accessible from other servers.
+Authentication is implemented using HTTP [basic
+authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). RPC
+HTTP requests must include a `Content-Type` header set to `text/plain` and a
+`Content-Length` header set to the size of the request body.
+
+The format of the request body and response data is based on [version 1.0 of the
+JSON-RPC specification](http://json-rpc<!--noref-->.org/wiki/specification). Specifically,
@harding

harding Aug 26, 2015

Contributor

It's best to put links in the the _includes/references.md file and then reference them here. For example, you would add this to the external links section of that file:

[JSON-RPC 1.0]: http://json-rpc.org/wiki/specification

Then change this link to,

The format of the request body and response data is based on [version 1.0 of the
JSON-RPC specification][JSON-RPC 1.0]. Specifically,

(Note change from parenthesis to brackets.

@carnesen

carnesen Aug 26, 2015

Contributor

Roger that. Replaced all -style links with external [][]-style ones.
@harding
Contributor

harding commented Aug 26, 2015

@carnesen I gave the diff a quick skim, and it looks excellent! Thanks! I left a few comments for now and I'll take a closer look later.

@harding harding added the Dev Docs label Aug 26, 2015

@harding
Contributor

harding commented Aug 27, 2015

I completed a more intensive review and didn't see any other issues. I also tested the batch processing using the instructions provided and had no problems. Once the previously-mentioned issues have been resolved, I think this should be good. Thanks again!
@harding
Contributor

harding commented Aug 27, 2015

@carnesen FYI, you can optionally add closes #1025 anywhere in your upcoming commit to automatically close issue #1025 when this PR gets merged. For details, see https://github.com/blog/1386-closing-issues-via-commit-messages
@harding
Contributor

harding commented Aug 27, 2015

Up to 532fc41 LGTM. Thanks! Preview: http://dg0.dtrt.org/en/developer-reference#remote-procedure-calls-rpcs

In the absence of critical feedback, this pull will be merged on Sunday.

@harding harding added the Merge Scheduled label Aug 27, 2015

@saivann saivann and 1 other commented on an outdated diff Aug 28, 2015

_includes/references.md
[HTTP longpoll]: https://en.wikipedia.org/wiki/Push_technology#Long_polling
[IP-to-IP payment protocol]: https://en.bitcoin.it/wiki/IP_Transactions
[IPv4-mapped IPv6 addresses]: http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses
[irc channels]: https://en.bitcoin.it/wiki/IRC_channels
+[JSON-RPC version 1.0]: http://json-rpc.org/wiki/specification
+[JSON-RPC version 2.0]: http://www.jsonrpc.org/specification#batch
@saivann

saivann Aug 28, 2015

Contributor

@carnesen @harding Maybe JSON-RPC version 2.0 could be renamed to a better representation of the link, for instance JSON-RPC request batching?

@harding

harding Aug 28, 2015

Contributor

Sure, that sounds good to me.
@saivann
Contributor

saivann commented Aug 28, 2015

@carnesen Thanks a lot of your recent contributions!

@harding harding merged commit e5aa4f8 into bitcoin-dot-org:master Sep 4, 2015
1 check passed

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

harding added a commit that referenced this pull request Sep 4, 2015

@harding
Merge pull #1030: Polish and expand Bitcoin Core RPC interface intro
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
e4b8f0c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment