gateways: document Content-Location #471
Conversation
and some cleanup
This is duplicated content, but is harmless, and having it here will save everyone a lot of headache debugging weird HTTP caching setups.
| A Client SHOULD include the `format` query parameter in the request URL, in | ||
| addition to the `Accept` header. This provides the best interoperability and | ||
| ensures consistent HTTP cache behavior across various gateway implementations. | ||
|
|
||
| A Gateway SHOULD include the | ||
| [`Content-Location`](#content-location-response-header) header in the response when: | ||
| - the request contains an `Accept` header specifying a well-known response | ||
| format, but the URL does not include the `format` query parameter | ||
| - the `format` parameter is present, but does not match the format from `Accept` |
There was a problem hiding this comment.
@hacdias I've added these clarifications as SHOULDs, the goal here is to push everyone towards including explicit ?format in requests – haves a lot of headache in debugging interop/caching problems.
We've always been doing this internally (including both format and Accept), this writes it down as suggested practice.
There was a problem hiding this comment.
Is it problematic then that some information in accept headers cannot be expressed in the format parameters (e.g. dfs, duplicates and version for CARs)
There was a problem hiding this comment.
Potentially, could cause issues at some point in the future when a single gateway supports something more than "the Kubo default" and clients actually request non-default CAR variant, including custom implementations with edge cases like #431.
That is why, to avoid cache override problems in the future, we revised position on these, add car-* URL params in #472. This allows us to explicitly list them in Content-Location when non-default CAR was requested (code for rainbow in ipfs/boxo#603)
gateway: car-* request query parameters
Document
Content-Locationas part of the work in ipfs/boxo#603.Context: ipfs/boxo#606