diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md index ca89bb61..51d75f09 100644 --- a/src/http-gateways/path-gateway.md +++ b/src/http-gateways/path-gateway.md @@ -145,7 +145,8 @@ block is in the local cache. ### `Accept` (request header) -Can be used for requesting specific response format +Can be used for requesting specific response format, and/or passing optional +content type parameters. For example: @@ -158,6 +159,15 @@ For example: - [application/cbor](https://www.iana.org/assignments/media-types/application/cbor) – same as `application/vnd.ipld.dag-cbor`, unless the CID's codec already is `cbor` (0x51). Then, the raw CBOR block can be returned as-is without any conversion. - [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) – requests a verifiable :cite[ipns-record] to be returned. Produces 400 Bad Request if the content is not under the IPNS namespace, or contains a path. +:::note + +A Client SHOULD include the [`format` query parameter](#format-request-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. + +::: + ### `Range` (request header) `Range` can be used for requesting specific byte range of UnixFS files and raw @@ -242,10 +252,14 @@ These are the equivalents: When both `Accept` HTTP header and `format` query parameter are present, `Accept` SHOULD take precedence. +:::note + 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 diff --git a/src/http-gateways/trustless-gateway.md b/src/http-gateways/trustless-gateway.md index 4e728d5d..1cf4c844 100644 --- a/src/http-gateways/trustless-gateway.md +++ b/src/http-gateways/trustless-gateway.md @@ -88,6 +88,15 @@ Below response types SHOULD be supported: A Gateway SHOULD return HTTP 400 Bad Request when running in strict trustless mode (no deserialized responses) and `Accept` header is missing. +:::note + +A Client SHOULD include the [`format` query parameter](#format-request-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. + +::: + ## Request Query Parameters ### :dfn[`format`] (request query parameter) @@ -97,10 +106,14 @@ Same as [`format`](https://specs.ipfs.tech/http-gateways/path-gateway/#format-re - `format=car` → `application/vnd.ipld.car` - `format=ipns-record` → `application/vnd.ipfs.ipns-record` +:::note + 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. +::: + ### :dfn[`dag-scope`] (request query parameter) Optional, `dag-scope=(block|entity|all)` with default value `all`, only available for CAR requests.