phantom/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-01-10 11:57:28 -03:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
bitcoin/doc
History
MarcoFalke 27cfaeed1e
Merge bitcoin/bitcoin#24098: rest: Use query parameters to control resource loading 
54b39cfb34 Add release notes (stickies-v)
f959fc0397 Update /<count>/ endpoints to use a '?count=' query parameter instead (stickies-v)
a09497614e Add GetQueryParameter helper function (stickies-v)
fff771ee86 Handle query string when parsing data format (stickies-v)
c1aad1b3b9 scripted-diff: rename RetFormat to RESTResponseFormat (stickies-v)
9f1c54787c Refactoring: move declarations to rest.h (stickies-v)

Pull request description:

  In RESTful APIs, [typically](https://rapidapi.com/blog/api-glossary/parameters/query/) path parameters  (e.g. `/some/unique/resource/`) are used to represent resources, and query parameters (e.g. `?sort=asc`) are used to control how these resources are being loaded through e.g. sorting, pagination, filtering, ...

  As first [discussed in #17631](https://github.com/bitcoin/bitcoin/pull/17631#discussion_r733031180), the [current REST api](https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md) contains two endpoints `/headers/` and `/blockfilterheaders/` that rather unexpectedly use path parameters to control how many (filter) headers are returned in the response. While this is no critical issue, it is unintuitive and we are still early enough to easily phase this behaviour out and ensure new endpoints (if any) do not have to stick to non-standard behaviour just for internal consistency.

  In this PR, a new `HTTPRequest::GetQueryParameter` method is introduced to easily parse query parameters, as well as two new `/headers/` and `/blockfilterheaders/` endpoints that use a count query parameter are introduced. The old path parameter-based endpoints are kept without too much overhead, but the documentation now points to the new query parameter-based endpoints as the default interface to encourage standardness.

  ## Behaviour change
  ### New endpoints and default values
  `/headers/` and `/blockfilterheaders/` now have 2 new endpoints that contain query parameters (`?count=<count>`) instead of path parameters (`/<count>/`), as described in REST-interface.md. Since query parameters can easily have default values, I have set this at 5 for both endpoints.

  **headers**
  `GET /rest/headers/<BLOCK-HASH>.<bin|hex|json>?count=<COUNT=5>`
  should now be used instead of
  `GET /rest/headers/<COUNT>/<BLOCK-HASH>.<bin|hex|json>`

  **blockfilterheaders**
  `GET /rest/blockfilterheaders/<FILTERTYPE>/<BLOCK-HASH>.<bin|hex|json>?count=<COUNT=5>`
  should now be used instead of
  `GET /rest/blockfilterheaders/<FILTERTYPE>/<COUNT>/<BLOCK-HASH>.<bin|hex|json>`

  ### Some previously invalid API calls are now valid
  API calls that contained query strings in the URI could not be parsed prior to this PR. This PR changes behaviour in that previously invalid calls (e.g. `GET /rest/headers/5/somehash.json?someunusedparam=foo`) would now become valid, as the query parameters are properly parsed, and discarded if unused.
  For example, prior to this PR, adding an irrelevant `someparam` parameter would be illegal:
  ```
  GET /rest/headers/5/0000004c6aad0c89c1c060e8e116dcd849e0554935cd78ff9c6a398abeac6eda.json?someparam=true
  ->
  Invalid hash: 0000004c6aad0c89c1c060e8e116dcd849e0554935cd78ff9c6a398abeac6eda.json?someparam=true
  ```
  **This behaviour change affects all rest endpoints, not just the 2 new ones introduced here.**

  *(Note: I'd be open to implementing additional logic to refuse requests containing unrecognized query parameters to minimize behaviour change, but for the endpoints that we currently have I don't really see the point for that added complexity. E.g. I don't see any scenarios where misspelling a parameter could lead to harmful outcomes)*

  ## Using the REST API

  To run the API HTTP server, start a bitcoind instance with the `-rest` flag enabled. To use the
  `blockfilterheaders` endpoint, you'll also need to set `-blockfilterindex=1`:
  ```
  ./bitcoind -signet -rest -blockfilterindex=1
  ```

  As soon as bitcoind is fully up and running, you should be able to query the API, for example by
  using curl on the command line: ```curl "127.0.0.1:38332/rest/chaininfo.json"```.
  To more easily parse the JSON output, you can also use tools like 'jq' or `json_pp`, e.g.:
  ```
  curl -s "localhost:38332/rest/blockfilterheaders/basic/0000004c6aad0c89c1c060e8e116dcd849e0554935cd78ff9c6a398abeac6eda.json?count=2" | json_pp .
  ```

  ## To do
  - [x] update `doc/release-notes`

  ## Feedback
  This is my first PR (hooray!). Please don't hold back on any feedback/comments/nits/... you may have, big or small, whether they are code, process, language, ... related. I welcome private messages too if there's anything you don't want to clutter the PR with. I'm here to learn and am grateful for everyone's input.

ACKs for top commit:
  stickies-v:
    I've had to push a tiny doc update to `REST-interface.md` (`git range-diff 219d728 9aac438 54b39cf`) since this was not merged for v23, but since there are no significant changes beyond theStack and jnewbery's ACKs I think this PR is now ready to be considered for merging? @MarcoFalke
  jnewbery:
    ACK 54b39cfb34
  theStack:
    re-ACK 54b39cfb34

Tree-SHA512: 3b393ffde34f25605ca12c0b1300799a19684b816a1d03aed38b0f5439df47bfe6a589ffbcd7b83fd2def6c9d00a1bae5e45b1d18df4ae998c617c709990f83f
2022-04-06 09:25:56 +02:00
..
man scripted-diff: Fix typo in stub manual pages 2021-01-12 16:46:55 +01:00
policy [doc] package deduplication 2022-02-14 10:04:51 +00:00
release-notes doc: Add historical release notes for 22.0 2021-09-14 13:20:48 +02:00
.gitignore Ignore Doxyfile generated from Doxyfile.in template. 2017-04-07 16:28:12 +02:00
assets-attribution.md [doc] Merge doc/assets-attribution.md into contrib/debian/copyright 2015-09-18 18:14:42 +02:00
assumeutxo.md doc: add assumeutxo notes 2021-10-04 16:40:00 -04:00
benchmarking.md doc: update doc/benchmarking.md 2021-06-24 11:15:29 +02:00
bips.md doc: Mention missing BIP157 in bips.md 2022-02-22 18:16:43 +01:00
bitcoin-conf.md doc: added info to bitcoin.conf doc 2021-07-06 09:32:37 -04:00
bitcoin_logo_doxygen.png Lossless image optimization 2013-12-02 10:10:22 +01:00
build-android.md build, qt: Use Android NDK r23 LTS 2021-12-05 03:00:02 +02:00
build-freebsd.md doc: mention that BDB is for the legacy wallet in build-freebsd.md 2022-03-23 15:35:29 +00:00
build-netbsd.md doc: mention that BDB is for the legacy wallet in build-netbsd.md 2022-03-24 10:53:04 +00:00
build-openbsd.md doc: remove CC_FOR_BUILD from OpenBSD build doc 2022-01-03 20:56:02 +08:00
build-osx.md Merge bitcoin/bitcoin#24585: doc: mention that BDB is for the legacy wallet in build-osx.md 2022-03-17 21:13:39 +01:00
build-unix.md doc: clarify that BDB is only required for the legacy wallet 2022-03-18 10:27:49 +00:00
build-windows.md doc: Install only "-posix" MinGW compiler when possible 2022-02-02 19:29:01 +02:00
cjdns.md Add and improve informational links in doc/cjdns.md 2022-04-01 16:11:14 +02:00
dependencies.md build, qt: bump Qt5 version to 5.15.3 2022-04-01 16:54:38 +02:00
descriptors.md Merge bitcoin/bitcoin#24043: Add (sorted)multi_a descriptor for k-of-n multisig inside tr 2022-03-04 07:28:23 -05:00
developer-notes.md doc: Document clang-tidy in dev notes 2022-03-25 08:18:51 +00:00
dnsseed-policy.md Correct spelling mistakes in doc folder 2015-10-18 06:25:43 +10:00
Doxyfile.in Generate doxygen documentation for test sources 2021-05-19 22:08:18 -07:00
external-signer.md Move external signer out of wallet module 2021-04-08 17:56:00 +02:00
files.md Ignore banlist.dat 2021-07-30 11:21:51 +02:00
fuzzing.md fuzz: parse the command line arguments in fuzz tests 2022-01-11 11:53:34 +01:00
guix.md docs: Point to contrib/guix/README.md in doc/guix.md 2021-01-08 11:40:01 -05:00
i2p.md doc: update i2p.md with cjdns, improve local addresses section 2022-03-22 12:54:23 +01:00
init.md doc: Replace tabs for spaces 2021-02-04 12:06:13 +00:00
JSON-RPC-interface.md Update 'Secure string handling' 2020-12-29 01:49:30 +05:30
managing-wallets.md Update doc to match new default wallet type 2022-02-09 07:38:48 +00:00
multiprocess.md multiprocess: Add comments and documentation 2021-04-23 03:02:50 -05:00
multisig-tutorial.md doc: update multisig-tutorial.md to default wallet type 2022-03-10 12:50:34 +01:00
p2p-bad-ports.md init, doc: improve -onlynet help and tor/i2p documentation 2022-03-03 16:14:01 +01:00
productivity.md doc: Add libnatpmp stuff 2021-01-07 18:07:10 +02:00
psbt.md doc: M-of-N multisig using descriptor wallets and PSBTs, as well as a signing flow 2021-08-16 10:43:07 +05:00
README.md doc, init: add links to doc/cjdns.md 2022-03-24 20:12:32 +01:00
README_doxygen.md doc: Improve doxygen readme navigation section 2019-09-23 19:22:06 -04:00
README_windows.txt doc: Remove version numbers from READMEs 2017-04-05 09:40:48 +02:00
reduce-memory.md doc: update reduce-memory.md peer connections info 2021-04-17 20:17:59 +02:00
reduce-traffic.md doc: Use precise permission flags where possible 2020-07-10 15:37:42 +02:00
release-notes-24098.md Add release notes 2022-04-05 13:19:37 -04:00
release-notes-24118.md Add sendall RPC née sweep 2022-03-29 16:37:47 -04:00
release-notes-24198.md doc: add wtxid info in release-notes 2022-02-09 21:15:19 -03:00
release-notes-24494.md [doc] release notes for random change target 2022-03-25 11:57:51 +00:00
release-notes-empty-template.md doc: Add template for empty release notes 2022-03-17 14:15:07 +01:00
release-notes.md doc: Add template for empty release notes 2022-03-17 14:15:07 +01:00
release-process.md Merge bitcoin/bitcoin#24583: doc: Add template for empty release notes 2022-04-05 09:11:11 +02:00
REST-interface.md Update /<count>/ endpoints to use a '?count=' query parameter instead 2022-04-05 13:19:37 -04:00
shared-libraries.md doc: libbitcoinconsensus: add missing error code description, fix NBitcoin link 2020-12-05 13:37:00 +01:00
tor.md doc: update tor.md with cjdns and getnodeaddresses, fix tor grep, 2022-03-22 12:54:21 +01:00
tracing.md tracing: misc follow-ups to 22902 2022-02-18 20:48:52 +05:30
translation_process.md doc: Remove unnecessary steps from translations update process 2021-07-03 21:31:29 +02:00
translation_strings_policy.md doc: Do not translate technical or extremely rare errors 2020-05-05 04:46:08 +03:00
zmq.md doc: Improve ZMQ documentation 2021-12-06 13:31:28 -03:00

README.md

Bitcoin Core

Setup

Bitcoin Core is the original Bitcoin client and it builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions, which requires a few hundred gigabytes of disk space. Depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more.

To download Bitcoin Core, visit bitcoincore.org.

Running

The following are some helpful notes on how to run Bitcoin Core on your native platform.

Unix

Unpack the files into a directory and run:

  • bin/bitcoin-qt (GUI) or
  • bin/bitcoind (headless)

Windows

Unpack the files into a directory, and then run bitcoin-qt.exe.

macOS

Drag Bitcoin Core to your applications folder, and then run Bitcoin Core.

Need Help?

Building

The following are developer notes on how to build Bitcoin Core on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc.

Development

The Bitcoin repo's root README contains relevant information on the development process and automated testing.

Resources

Miscellaneous

License

Distributed under the MIT software license.