mirror of
https://github.com/bitcoin/bitcoin.git
synced 2024-05-17 23:56:39 +00:00
27cfaeed1e
54b39cfb342d10a448d49299c715e3a25c2aca4a Add release notes (stickies-v) f959fc0397c3f3615e99bc28d2df549d9d52f277 Update /<count>/ endpoints to use a '?count=' query parameter instead (stickies-v) a09497614e9bb603fff36286d9611a25b23eeb02 Add GetQueryParameter helper function (stickies-v) fff771ee864975cee8c831651239bac95503c37a Handle query string when parsing data format (stickies-v) c1aad1b3b95b7c6bdf05e0c2095aba2f2db8310b scripted-diff: rename RetFormat to RESTResponseFormat (stickies-v) 9f1c54787c81177dd56a31c881a9ad2834a122dc 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 54b39cfb342d10a448d49299c715e3a25c2aca4a theStack: re-ACK 54b39cfb342d10a448d49299c715e3a25c2aca4a Tree-SHA512: 3b393ffde34f25605ca12c0b1300799a19684b816a1d03aed38b0f5439df47bfe6a589ffbcd7b83fd2def6c9d00a1bae5e45b1d18df4ae998c617c709990f83f
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) orbin/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?
- See the documentation at the Bitcoin Wiki for help and more information.
- Ask for help on Bitcoin StackExchange.
- Ask for help on #bitcoin on Libera Chat. If you don't have an IRC client, you can use web.libera.chat.
- Ask for help on the BitcoinTalk forums, in the Technical Support board.
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.
- Dependencies
- macOS Build Notes
- Unix Build Notes
- Windows Build Notes
- FreeBSD Build Notes
- OpenBSD Build Notes
- NetBSD Build Notes
- Android Build Notes
Development
The Bitcoin repo's root README contains relevant information on the development process and automated testing.
- Developer Notes
- Productivity Notes
- Release Notes
- Release Process
- Source Code Documentation (External Link)
- Translation Process
- Translation Strings Policy
- JSON-RPC Interface
- Unauthenticated REST Interface
- Shared Libraries
- BIPS
- Dnsseed Policy
- Benchmarking
Resources
- Discuss on the BitcoinTalk forums, in the Development & Technical Discussion board.
- Discuss project-specific development on #bitcoin-core-dev on Libera Chat. If you don't have an IRC client, you can use web.libera.chat.
Miscellaneous
- Assets Attribution
- Assumeutxo design
- bitcoin.conf Configuration File
- CJDNS Support
- Files
- Fuzz-testing
- I2P Support
- Init Scripts (systemd/upstart/openrc)
- Managing Wallets
- Multisig Tutorial
- P2P bad ports definition and list
- PSBT support
- Reduce Memory
- Reduce Traffic
- Tor Support
- Transaction Relay Policy
- ZMQ
License
Distributed under the MIT software license.