IPIP-0523: Prefer format request param over Accept header #523
Conversation
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
achingbrain
force-pushed
the
feat/ipip-accept-vs-format
branch
from
8c22f1a to
f76b2d5
Compare
Browsers will always send an Accept header so if present the format request param should take priority, not the other way round as the spec currently says.
achingbrain
force-pushed
the
feat/ipip-accept-vs-format
branch
from
a0ec721 to
824cf89
Compare
🚀 Build Preview on IPFS ready
|
- clarify format is URL query param, Accept is HTTP header - expand Compatibility with HTTP caching rationale - add Security and Alternatives sections - update precedence rule in both path-gateway and trustless-gateway
update car-version, car-order, car-dups to match IPIP-0523: URL query parameter SHOULD take precedence over Accept header
lidel
added a commit
to ipfs/boxo
that referenced
this pull request
Dec 1, 2025
…pt header this change simplifies precedence rules by making the ?format= URL query parameter always take priority over the Accept HTTP header when both are present. in practice, this is largely compatible with existing browser use cases since browsers send Accept headers with wildcards which were already treated as non-specific. prioritizing ?format= also ensures deterministic HTTP caching behavior, protecting against CDNs that comingle different response types under the same cache key. the only breaking change is for edge cases where a client sends both a specific Accept header and a different ?format= value. previously Accept would win, now ?format= wins. this scenario is rare and arguably represents client misconfiguration. when detected, gateway returns HTTP 400 to signal the ambiguity. specs: ipfs/specs#523 tests: ipfs/gateway-conformance#252
This was referenced Dec 1, 2025
lidel
approved these changes
Dec 2, 2025
Member
There was a problem hiding this comment.
Thank you for cleaning this up. This is def. a technical debt we asccumulated by adding features over time. Work on Service Worker gateway makes it a good time to do this.
lgtm, added some meat to missing/empty sections
GO implementation is ready – details in ipfs/gateway-conformance#252 (review) (if no concerns, we will merge later this week and ship in Kubo 0.40)
| Users will be able to use the `format` URL query parameter to control the | ||
| response type of requests made from browser address bars. | ||
|
|
||
| ### Compatibility |
Member
There was a problem hiding this comment.
ℹ️ @achingbrain fyi I've expanded the Compatibility section. While formally this is a breaking change, in practice boxo/gateway already had an escape hatch in customResponseFormat which prioritized format if Accept has a wildcard or used something other than raw, car or ipns-record
(imo this is good news, means IPIP is actually cleaning up and formalizing real world behavior in browsers)
19 tasks
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.
Browsers will always send an Accept header so if present the format request param should take priority, not the other way round as the spec currently says.
Things to land before ratifying (merging) this IPIP