Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: format/accept SHOULD note more prominent #478

Merged
merged 1 commit into from
Jul 2, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading