From 623455326aa332d8c4766b3203a195dac625c289 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Mon, 17 Apr 2023 17:31:30 +0200 Subject: [PATCH 1/2] wip: data onboarding --- src/http-gateways/writable-gateway.md | 46 ++++++++++++++++++++++ src/ipips/ipip-0401.md | 55 +++++++++++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 src/http-gateways/writable-gateway.md create mode 100644 src/ipips/ipip-0401.md 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/). From 82a5cb7ae6eab3b4d8f637cffcb827351f3ebf18 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 18 Sep 2023 22:14:20 +0200 Subject: [PATCH 2/2] chore: change ipip title remove mention of legacy feature removed from Kubo. shift narrative towards reusing HTTP Semantics. --- src/http-gateways/writable-gateway.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/http-gateways/writable-gateway.md b/src/http-gateways/writable-gateway.md index 86cf50bca..bb5b4ba7d 100644 --- a/src/http-gateways/writable-gateway.md +++ b/src/http-gateways/writable-gateway.md @@ -1,7 +1,7 @@ --- -title: Writable Gateway Specification +title: Data Onboarding with HTTP Semantics description: > - Writable Gateways are a way of onboarding data into IPFS via the HTTP gateways. It exposes a POST endpoint + Reusing HTTP Semantics for 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: