doc: document json rpc endpoints #27225

willcl-ark commented at 9:02 AM on March 8, 2023: member

fixes #20246

This documents the two JSON-RPC endpoints available, details when they are active, specifies when they can or must be used, and outlines some known behaviour quirks.

DrahtBot commented at 9:02 AM on March 8, 2023: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	fanquake
Concept ACK	pinheadmz, kristapsk

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

DrahtBot added the label Docs on Mar 8, 2023

fanquake requested review from luke-jr on Mar 8, 2023

fanquake requested review from stickies-v on Mar 8, 2023

fanquake commented at 10:54 AM on March 8, 2023: member

Concept ACK

in doc/JSON-RPC-interface.md:13 in 86cff0ee0c outdated

   4 | @@ -5,6 +5,36 @@ The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI
   5 |  option. In the GUI it is possible to execute RPC methods in the Debug Console
   6 |  Dialog.
   7 |  
   8 | +## Endpoints
   9 | +
  10 | +There are two JSON-RPC endpoints on the server:
  11 | +
  12 | +1. `/`
  13 | +2. `/wallet/<walletname>/`

pinheadmz commented at 3:13 PM on March 8, 2023:

A few ideas about these:

could include full path http://localhost:{port}/
could list relevant ports per network (i.e. main=8332, regtest=18443 etc)
not sure if this applies here but I'm used to seeing API endpoints with variables expressed like /wallet/:walletname, at least for REST APIs. I dunno if there is otherwise a convention for that

willcl-ark commented at 4:57 PM on March 8, 2023:

Personally I feel it's clearer just to use the endpoints themselves, rather than cluttering with hosts and ports.

Also, we have examples now!

in doc/JSON-RPC-interface.md:18 in 86cff0ee0c outdated

  13 | +2. `/wallet/<walletname>/`
  14 | +
  15 | +### `/` endpoint
  16 | +
  17 | +This endpoint is always active and can service both wallet and non-wallet
  18 | +requests when there are zero or one wallets loaded.

pinheadmz commented at 3:17 PM on March 8, 2023:

This endpoint is always active for non-wallet requests, and can service wallet requests when exactly one wallet is loaded.

willcl-ark commented at 3:27 PM on March 8, 2023:

I see your point here, but I was also trying to distinguish: active=enabled, services=wallet/non-wallet.

How about:

This endpoint is always active. It can always service non-wallet requests and can service wallet requests when exactly one wallet is loaded.

pinheadmz commented at 3:47 PM on March 8, 2023:

👍

willcl-ark commented at 4:57 PM on March 8, 2023:

Done

in doc/JSON-RPC-interface.md:22 in 86cff0ee0c outdated

  17 | +This endpoint is always active and can service both wallet and non-wallet
  18 | +requests when there are zero or one wallets loaded.
  19 | +
  20 | +### `/wallet/<walletname>/` endpoint
  21 | +
  22 | +This endpoint is only activated when the wallet component has been compiled in

pinheadmz commented at 3:19 PM on March 8, 2023:

It is also always active for non-wallet requests before any wallets are loaded.

willcl-ark commented at 3:29 PM on March 8, 2023:

(but only when the wallet is compiled in).

Also I think i've covered that it handles both types of request when no wallet is loaded in the Quirks section?

in doc/JSON-RPC-interface.md:26 in 86cff0ee0c outdated

  21 | +
  22 | +This endpoint is only activated when the wallet component has been compiled in
  23 | +and can service both wallet and non-wallet requests. It MUST be used for wallet
  24 | +requests when two or more wallets are loaded.
  25 | +
  26 | +This endpoint is equivalent to using bitcoin-cli with the `-rpcwallet=` parameter.

pinheadmz commented at 3:19 PM on March 8, 2023:

This is the endpoint used by bitcoin-cli when a `-rpcwallet=` parameter is passed in.

willcl-ark commented at 3:29 PM on March 8, 2023:

Agree with this.

willcl-ark commented at 5:00 PM on March 8, 2023:

Done

in doc/JSON-RPC-interface.md:30 in 86cff0ee0c outdated

  24 | +requests when two or more wallets are loaded.
  25 | +
  26 | +This endpoint is equivalent to using bitcoin-cli with the `-rpcwallet=` parameter.
  27 | +
  28 | +Best practice would dictate using the `/wallet/<walletname>/` endpoint for ALL
  29 | +requests when multiple wallets are in use.

pinheadmz commented at 3:21 PM on March 8, 2023:

actually seems like its the right endpoint to use for all requests all the time! For non wallet requests you can still use /wallet with no wallet name

$ curl http://u:p@localhost:18443/wallet/ --data '{"method":"getblockcount"}'
{"result":206,"error":null,"id":null}

willcl-ark commented at 3:31 PM on March 8, 2023:

Oh, I didn't know you could use the endpoint without a wallet name at all!

IMO it makes sense to specify that it should be used with the wallet/<walletname>/ syntax for multiwallet (as designed?)

pinheadmz commented at 3:48 PM on March 8, 2023:

yeah i dunno whats best to reccomend. I think personally Id use / for node requests and /wallet/walletname for any wallet request no matter how many wallets are loaded.

willcl-ark commented at 4:58 PM on March 8, 2023:

Leaving this for now, as using the bare /wallet/ endpoint could be considered unsupported behaviour.

in doc/JSON-RPC-interface.md:36 in 86cff0ee0c outdated

  31 | +### Quirks:
  32 | +
  33 | +* With more than one wallet loaded the `/` endpoint will still be able to
  34 | +service non-wallet requests.
  35 | +* When active the `/wallet/<walletname>/` endpoint can still be used when no
  36 | +wallet is loaded by providing a dummy `walletname`.

pinheadmz commented at 3:22 PM on March 8, 2023:

I think these can be folded in above if you like my suggestions.

I think a few curl examples might be appropriate here as well since this document is covering raw endpoint stuff

willcl-ark commented at 3:32 PM on March 8, 2023:

Again I think I agree here, especially seeing as there are no /wallet/ examples given in RPCHelp

willcl-ark commented at 5:00 PM on March 8, 2023:

Removed quirks

unknown approved

unknown commented at 3:22 PM on March 8, 2023: none

ACK https://github.com/bitcoin/bitcoin/pull/27225/commits/86cff0ee0cb78f5eb2568e7e863eb72baa571a53

Error is also helpful if someone is unaware of this and tries to use / endpoint with 2 or more wallets for wallet based RPC commands.

{
    "result": null,
    "error": {
        "code": -19,
        "message": "Wallet file not specified (must request wallet RPC through /wallet/<filename> uri-path)."
    },
    "id": "test"
}

pinheadmz commented at 3:22 PM on March 8, 2023: member

concept ACK

willcl-ark force-pushed on Mar 8, 2023

in doc/JSON-RPC-interface.md:39 in 36748e87fc outdated

  34 | +```sh
  35 | +# Get block count from the / endpoint when rpcuser=alice and rpcport=38332
  36 | +$ curl --user alice --data-binary '{"jsonrpc": "1.0", "id": "0", "method": "getblockcount", "params": []}' -H 'content-type: text/plain;' localhost:38332/
  37 | +
  38 | +# Get balance from the /wallet/walletname endpoint when rpcuser=alice, rpcport=38332 and rpcwallet=desc-wallet
  39 | +$ curl --user alice --data-binary '{"jsonrpc": "1.0", "id": "0", "method": "getbalance", "params": []}' -H 'content-type: text/plain;' localhost:38332/wallet/desc-wallet

pinheadmz commented at 6:07 PM on March 8, 2023:

If this gets merged before #27101, remind me to update to 2.0 ;-)

Technically I think jsonrpc:"1.0" isn't necessary and doesn't actually do anything.

unknown commented at 10:17 AM on March 9, 2023:

Why are the examples using signet port? I think we should use mainnet port (8332) same as all the RPC examples.

willcl-ark commented at 10:52 AM on March 9, 2023:

I'm happy to be persuaded either way here, no particular reason for using signet (other than I was using it for testing). Although I personally don't think it matters much as the comment for each shows which variables are being used

kristapsk commented at 6:13 PM on March 8, 2023: contributor

Concept ACK

kristapsk commented at 6:14 PM on March 8, 2023: contributor

Nit - there is typo in commit message / PR title (s/docment/document/).

doc: document json rpc endpoints

fixes #20246

Document both JSON-RPC endpoints, when they are active and which types
of requests they are able to service.

Adds two example curl requests, one for each endpoint.

65e3abcbf2

willcl-ark commented at 8:44 AM on March 9, 2023: member

Nit - there is typo in commit message / PR title (s/docment/document/).

Thanks, i've updated this in 65e3abcbf

willcl-ark force-pushed on Mar 9, 2023

kristapsk commented at 9:25 AM on March 9, 2023: contributor

Nit - there is typo in commit message / PR title (s/docment/document/).

Thanks, i've updated this in 65e3abcbf

You should also edit PR title. It is used by github-merge.py.

willcl-ark renamed this:
~~doc: docment json rpc endpoints~~
doc: document json rpc endpoints
on Mar 9, 2023

willcl-ark commented at 9:34 AM on March 9, 2023: member

Thanks, I thought that updated from the force push, but apparently not. Now also done :)

fanquake approved

fanquake commented at 3:25 PM on June 2, 2023: member

ACK 65e3abcbf2b9e818f3b9f1ba35f3cfe7df5e3811 - Seems fine. Can be improved if need be.

fanquake merged this on Jun 2, 2023

fanquake closed this on Jun 2, 2023

sidhujag referenced this in commit 014f78c5cd on Jun 2, 2023

bitcoin locked this on Jun 1, 2024