Skip to content

Commit

Permalink
chore: format/accept SHOULD note more prominent
Browse files Browse the repository at this point in the history
  • Loading branch information
lidel committed Jul 2, 2024
1 parent 27a9aaa commit cb080e9
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 1 deletion.
16 changes: 15 additions & 1 deletion src/http-gateways/path-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions src/http-gateways/trustless-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Expand Down

0 comments on commit cb080e9

Please sign in to comment.