#35909 rest: Allow fetching stale header
| Reviewability | Reviews | Agreement | Size | ||||
|---|---|---|---|---|---|---|---|
| #35909 rest: Allow fetching stale header | Waiting on author | 1 | Mild | 76 + 58 tests | |||
|
|
|
|
| |||
Reviewability: ReadyStalePaused Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs. Size: lines added or modified outside tests, then in tests; greener = smaller. | |||||||
Goal
Adds an optional activechainonly boolean query parameter to the /rest/headers/ endpoint to allow fetching headers not on the active chain. When activechainonly is set to false and count is 1, the endpoint returns the header even if it belongs to a stale branch. The PR also extracts REST boolean query parameter parsing into a shared helper function used by headers and mempool endpoints.
Problem: Currently, the /rest/headers/ endpoint only returns block headers that are part of the active chain, returning an empty list for stale blocks. Clients relying on the REST interface cannot inspect stale block headers or trace ancestor headers during a chain reorganization without falling back to the getblockheader RPC.
Evidence of importance:
- Resolves issue #35897 ('rest: Allow fetching headers from stale branches').
- Author states that 'Being able to request stale block headers is useful for clients that want to learn the ancestors of a blockhash e.g. when following a re-org up and matches the functionality of the getblockheader RPC.'
Reviewability
Paused · Waiting on author
Open objection from 0xB10C with no author reply for 32 days; review would repeat what has been asked.
Waiting on (from the thread read):
- author: response to 0xB10C's suggestion regarding a dedicated endpoint 2026-09-16
- author: response to 0xB10C regarding REST API weirdness and endpoint design 2026-09-16
Agreement
Mild
objection that needs an answer has none yet (0xB10C)
Thread notes: Re-classified 0xB10C's claim as an approach suggestion rather than an objection since it weighs alternative designs proposed in the PR description rather than naming a concrete defect. Recorded jeanpablojp's release note naming question and author reply, and added w0xlt's Concept ACK. / Added Concept ACK from w0xlt and recorded release note filename question from jeanpablojp under the re-read rules. 0xB10C's objection regarding REST API design remains open awaiting author response.
Objections, suggestions, and questions:
| Reviewer | Type | Harm, request, or question | Status | Must be | Author replied | Quote |
|---|---|---|---|---|---|---|
| jeanpablojp (contributor) | question, style | Whether the release note file should be renamed to release-notes-35909.md before merge | answered · author replied that a uniquely named release note file is fine per developer notes | answered | yes | 2026-08-15: 'shouldn't this be renamed to `release-notes-35909.md` before merge?' Status from: 2026-08-15: davidgumberg: 'I think as long as the release note file is uniquely named it's fine' |
| 0xB10C (member) | objection, approach | Consider a dedicated /header/ endpoint instead of requiring count=1 and activechainonly=false on /rest/headers/ | open | answered | no | 2026-09-16: '`/rest/headerS` with `count=1` and `activechainonly=false` feels like introducing more REST API weirdness?' |
Support:
- sedited (member) (Concept ACK, 2026-08-06): (no reason given) [not substantive]
- jeanpablojp (contributor) (Tested ACK, 2026-08-15) [both]: solves the issue's use case without opening a new endpoint to maintain
- 0xB10C (member) (Concept ACK, 2026-09-16) [read]: needed for fork-observer which uses getblockheader RPC
- w0xlt (contributor) (Concept ACK, 2026-09-30): (no reason given) [not substantive]
Participants:
- sedited (member, support, 1 statements 2026-08-06 to 2026-08-06): Concept ACK without elaboration
- jeanpablojp (contributor, support, 2 statements 2026-08-15 to 2026-08-15): Tested ACK preferring query param approach; asked about release note naming
- 0xB10C (member, objection, 1 statements 2026-09-16 to 2026-09-16): Concept ACK citing fork-observer, but questioned whether query param adds REST API weirdness over a dedicated endpoint
- w0xlt (contributor, support, 1 statements 2026-09-30 to 2026-09-30): Concept ACK
Files
59 lines under test/bench/ci.
- src/rest.cpp +59/-25
- src/test/rest_tests.cpp +44/-0
- test/functional/interface_rest.py +14/-1
- doc/REST-interface.md +7/-2
- doc/release-notes-reststaleheader.md +5/-0
- src/rest.h +5/-0
Card
The short text the ranking pass compares across PRs.
Adds an activechainonly query parameter to the REST headers endpoint to allow querying single block headers from stale branches when set to false with count=1. Currently, /rest/headers returns empty arrays for any block not on the active chain, leaving REST clients unable to trace ancestor headers during reorgs without JSON-RPC. The author notes this brings parity with the getblockheader RPC and resolves issue #35897. The change also deduplicates boolean query parameter parsing across the REST interface.
Data
thread read through 2026-09-30 (6 statements), head bd9d6bc4e9
labels: RPC/REST/ZMQ
Categories
RPC / REST / ZMQ
P3 · user request (ranking pass: Moved down 9: REST/RPC parity gap with a named consumer, still an additive feature.)
Addresses a gap in the REST interface that forced applications like fork-observer to fall back to RPC getblockheader when tracing reorgs. It matches existing RPC capability and resolves issue #35897 with confirmed external consumer interest.
Membership: Carries RPC/REST/ZMQ label and modifies REST endpoint query parameter handling in src/rest.cpp.
Factors: security/stability 0, bug 0, performance 0, user value 2, leverage 0