Skip to content

Commit

Permalink
remove non dag-* variants
Browse files Browse the repository at this point in the history
  • Loading branch information
hacdias committed Jan 19, 2023
1 parent e4cbfd1 commit 3e5fbc7
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 21 deletions.
23 changes: 8 additions & 15 deletions IPIP/0328-gateway-json-cbor-response-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@

## Summary

Add support for the [DAG-JSON], [DAG-CBOR], JSON and CBOR response formats in
the [HTTP Gateway](../http-gateways/).
Add support for the [DAG-JSON] and [DAG-CBOR] response formats to the
[HTTP Gateway](../http-gateways/).

## Motivation

Expand Down Expand Up @@ -41,8 +41,8 @@ to storing and fetching CBOR and JSON in IPFS.

## Detailed design

The solution is to allow the Gateway to support serializing data as [DAG-JSON],
[DAG-CBOR], JSON and CBOR by requesting them using either the `Accept` HTTP header
The solution is to allow the Gateway to support serializing data as [DAG-JSON]
and [DAG-CBOR] by requesting them using either the `Accept` HTTP header
or the `format` URL query. In addition, if the resolved CID is of one of the
aforementioned types, the gateway should be able to resolve them instead of
failing with `node type unknown`.
Expand Down Expand Up @@ -99,19 +99,12 @@ strict enough:

### Alternatives

If we do not introduce DAG-JSON, DAG-CBOR, JSON and CBOR response formats in
the gateway, the usage of IPFS is constricted to files and directories represented
If we do not introduce DAG-JSON and DAG-CBOR, response formats in the gateway,
the usage of IPFS is constricted to files and directories represented
by UnixFS (DAG-PB) codec. Therefore, if a user wants to store JSON and/or CBOR
in IPFS, they have to wrap it as a UnixFS file in order to be able to fetch it
through the gateway. That adds size and processing overhead.

In addition, we could introduce only DAG-JSON and DAG-CBOR. However, not
supporting the generic variants, JSON and CBOR, would lead to poor UX. The
ability to retrieve DAG-JSON as `application/json` is an important step
for the interoperability of the HTTP Gateway with web browsers and other tools
that expect specific Content Types. Namely, `Content-Type: application/json` with
`Content-Disposition: inline` allows for JSON preview to be rendered in a web browser.

Finally, we considered supporting pathing within both DAG and non-DAG variants
of the JSON and CBOR codecs. Pathing within these documents could lead to responses
with extracts from the document. For example, if we have the document:
Expand Down Expand Up @@ -143,8 +136,8 @@ However, supporting this raises questions whose answers are not clearly defined
or agreed upon yet. Right now, pathing is only supported over CID-based Links,
such as Tag 42 in CBOR. In addition, some HTTP headers regarding caching are based
on the CID, and adding extraction pathings would not be clear. Giving users the
possibility to retrieve JSON, CBOR, DAG-JSON AND DAG-CBOR documents through the
gateway is, in itself, a progress and will open the doors for new tools and explorations.
possibility to retrieve DAG-JSON and DAG-CBOR documents through the gateway is,
in itself, a progress and will open the doors for new tools and explorations.

### Copyright

Expand Down
6 changes: 0 additions & 6 deletions http-gateways/PATH_GATEWAY.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,8 +186,6 @@ For example:
- [application/x-tar](https://en.wikipedia.org/wiki/Tar_(computing)) – returns UnixFS tree (files and directories) as a [TAR](https://en.wikipedia.org/wiki/Tar_(computing)) stream. Returned tree starts at a root item which name is the same as the requested CID. Produces 400 Bad Request for content that is not UnixFS.
- [application/vnd.ipld.dag-json](https://www.iana.org/assignments/media-types/application/vnd.ipld.dag-json) – requests [IPLD Data Model](https://ipld.io/docs/data-model/) representation serialized into [DAG-JSON format](https://ipld.io/docs/codecs/known/dag-json/). If the requested CID already has `dag-json` (0x0129) codec, data is validated as DAG-JSON before being returned as-is. Invalid DAG-JSON produces HTTP Error 500.
- [application/vnd.ipld.dag-cbor](https://www.iana.org/assignments/media-types/application/vnd.ipld.dag-cbor) – requests [IPLD Data Model](https://ipld.io/docs/data-model/) representation serialized into [DAG-CBOR format](https://ipld.io/docs/codecs/known/dag-cbor/). If the requested CID already has `dag-cbor` (0x71) codec, data is validated as DAG-CBOR before being returned as-is. Invalid DAG-CBON produces HTTP Error 500.
- [application/json](https://www.iana.org/assignments/media-types/application/json) – same as `application/vnd.ipld.dag-json`, unless the CID's codec already is `json` (0x0200). Then, the raw JSON block can be returned.
- [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.

### `Range` (request header)

Expand Down Expand Up @@ -598,10 +596,6 @@ The following response formats are selected according to the codec of the resolv
- Directory
- Generated HTML with directory index (see [additional notes here](#generated-html-with-directory-index))
- When `index.html` is present, gateway can skip generating directory index and return it instead
- JSON (0x0200)
- Bytes representing a JSON file, see [application/json](https://www.iana.org/assignments/media-types/application/json).
- CBOR (0x51)
- Bytes representing a CBOR file, see [application/cbor](https://www.iana.org/assignments/media-types/application/cbor)
- DAG-JSON (0x0129)
- If the `Accept` header includes `text/html`: generated HTML with options to download DAG-JSON as-is, or converted to DAG-CBOR.
- Bytes representing a DAG-JSON file, see [application/vnd.ipld.dag-json](https://www.iana.org/assignments/media-types/application/vnd.ipld.dag-json)
Expand Down

0 comments on commit 3e5fbc7

Please sign in to comment.