diff --git a/src/http-gateways/writable-gateway.md b/src/http-gateways/writable-gateway.md new file mode 100644 index 000000000..86cf50bca --- /dev/null +++ b/src/http-gateways/writable-gateway.md @@ -0,0 +1,46 @@ +--- +title: Writable Gateway Specification +description: > + Writable Gateways are a way of onboarding data into IPFS via the HTTP gateways. It exposes a POST endpoint + that supports multiple input types, then ingests the data into IPFS, returning its final location. +date: 2023-04-17 +editors: + - name: Henrique Dias + github: hacdias + url: https://hacdias.com/ +--- + +# Writable Gateway Specification + +Writable Gateway is an extension of :cite[path-gateway], which allows data onboarding +to IPFS via HTTP endpoints. This allows for more interoperability with the remaining +of the web, and allows for more ways of adding data to IPFS. + +# HTTP API + +This API is a superset of the HTTP API of :cite[path-gateway]. The differences are +documented below. The main difference is the introduction of a `POST` endpoint. + +## `POST /ipfs` + +Onboards new data to the IPFS node behind the gateway. The onboarded data can be +of any of the following types and be specified via the `Content-Type` header: + +- [`application/vnd.ipld.raw`] - adds raw [blocks] to the gateway. The data in +the request body is assumed to be pure blocks of data, with no specific structure. +- [`application/vnd.ipld.car`] - adds a [CAR] to the gateway. The data in the request +body is assumed to be a CAR file. +- [`application/x-tar`] - adds a [TAR] archive to the gateway. The data in the request +body is assumed to be a TAR archive containing a directory tree that will be added +as a UnixFS directory to IPFS. + +In case of success, the request will return a `201 Created` status code, as +well as a `Content-Location` header containing the content path of the newly added +resource. + +[`application/vnd.ipld.raw`]: https://www.iana.org/assignments/media-types/application/vnd.ipld.raw +[`application/vnd.ipld.car`]: https://www.iana.org/assignments/media-types/application/vnd.ipld.car +[`application/x-tar`]: https://en.wikipedia.org/wiki/Tar_(computing) +[blocks]: https://docs.ipfs.io/concepts/glossary/#block +[CAR]: https://docs.ipfs.io/concepts/glossary/#car +[TAR]: https://en.wikipedia.org/wiki/Tar_(computing) diff --git a/src/ipips/ipip-0401.md b/src/ipips/ipip-0401.md new file mode 100644 index 000000000..859187d3a --- /dev/null +++ b/src/ipips/ipip-0401.md @@ -0,0 +1,55 @@ +--- +title: "IPIP-0401: Data Onboarding (POST) via Writable Gateways" +date: 2023-04-17 +order: 401 +tags: ['ipips'] +ipip: proposal +editors: + - name: Henrique Dias + github: hacdias + url: https://hacdias.com/ + - name: Marcin Rataj + github: lidel +relatedIssues: + - https://github.com/ipfs/specs/issues/375 +--- + +## Summary + +This IPIP introduces a new gateway extension, named Writable Gateway, that +provides a vendor-agnostic protocol for onboarding arbitrary data to IPFS by +using a regular HTTP `POST` request. + +## Motivation + +The IPFS implementation Kubo has provided a non-standardized version of a writable +gateway for the past few years. This gateway has received little attention over the +years and there have been requests from users in order to get a + +## Detailed design + +## Test fixtures + +## Design rationale + +### User benefit + +### Compatibility + +This IPIP is backwards compatible: it adds a new opt-in functionality for the gateway, +not modifying any existing behaviours. + +### Security + +Introducing data onboarding via HTTP Gateways opens possibility for data creation +and modification through the gateway. It is likely that not all users will want to +have Writable Gateways enabled, or that they are available to everyone. Therefore, +we recommend that the implementer includes an Authentication method. This +authentication method can be application dependent and is therefore not specified. + +### Alternatives + + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).