Repository navigation
fix(openapi): align response schemas with actual API responses - #5674
Merged
Merged
Conversation
martinconic
force-pushed
the
fix/openapi-response-drift
branch
from
October 22, 2026 09:47
c4b1ced to
64a47e0
Compare
martinconic
requested review from
acud,
akrem-chabchoub,
aloknerurkar,
gacevicljubisa and
sbackend123
October 22, 2026 14:08
sbackend123
reviewed
Oct 22, 2026
sbackend123
reviewed
Oct 22, 2026
sbackend123
approved these changes
Oct 23, 2026
Fix the mismatches found by running Schemathesis against a node: - error responses are application/json, and reasons are objects with field and error, not strings - Ethereum addresses are returned with a 0x prefix - balance thresholds, last cheques, logger lists and topology peer lists can be null - tag address is an empty string until the upload is finalized - document the 429 response of /pins/check Exclude /pins/check from the conformance run, because it streams NDJSON with an application/json content type. Bump the API version to 8.2.2. Refs: #4974
- require the 0x prefix on EthereumAddress, which is only used for common.Address fields - document the batch owner as hex without the 0x prefix - accept both forms on the feeds owner and withdraw address inputs - describe balance thresholds as always null on /balances and /consumed, and point to /accounting - explain when /pins/check returns 429
martinconic
force-pushed
the
fix/openapi-response-drift
branch
from
October 23, 2026 10:07
66fde2d to
70785e8
Compare
This was referenced Oct 23, 2026
aloknerurkar
approved these changes
Oct 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checklist
Description
I ran the new Schemathesis conformance check from #5673 against a testnet node. It found 29 places where the spec disagrees with what bee actually returns. This PR fixes the spec to match the real responses. No Go code changes, and API behavior doesn't change.
What was wrong in the spec
application/problem+jsonapplication/jsonreasonsis a list of strings{field, error}objects0xprefix0xprefixed, EIP-55 checksummed. Batchowneris the exception: plain hex without0x/wallet,/addresses, chequebook, transactions, envelopenulllastreceived/lastsentcheques,/loggers,/topologypeer listsnull(thresholds are in/accounting)/balances,/consumedaddressis always a 64-char hex/tags/pins/checkcan only fail with 500/pins/checkFor inputs,
/feeds/{owner}and/wallet/withdrawaccept the address with or without0x./soc/{owner}only accepts it without0x, because that handler decodes plain hex.Result
About the oasdiff report on this PR
oasdiff will show about 350 "breaking" changes. Almost all of them are the same two fixes to the shared error response (content type and
reasons), repeated for every endpoint. None of this changes what bee sends. The spec now describes what clients already receive, so clients that work against the real API are not affected.Not fixed here
/pins/checkstreams NDJSON but sends aContent-Type: application/jsonheader. The spec already describes the stream correctly. Fixing the header is a code change, so I left it out and excluded/pins/checkfrom the conformance run for now.GET /chunks/0000…0000returns 500read chunk failedinstead of a 4xx. This looks like a handler bug, not spec drift.Open API Spec Version Changes (if applicable)
8.2.1→8.2.2(patch: the documentation is corrected to match existing behavior).Motivation and Context (Optional)
Part of #4974: getting the spec accurate enough that bee-js and other clients can be generated from it. Once this is merged and the conformance check stays green, we can make it blocking.
Related Issue (Optional)
#4974, depends on #5673
AI Disclosure