From cb080e909cc1280f90969182cff47e012d9388b2 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Tue, 2 Jul 2024 15:25:06 +0200
Subject: [PATCH] chore: format/accept SHOULD note more prominent

---
 src/http-gateways/path-gateway.md      | 16 +++++++++++++++-
 src/http-gateways/trustless-gateway.md | 13 +++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

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.