Writeable HTTP Gateways

What is a Writeable Gateway?

By default, an HTTP gateway for IPFS only supports the HTTP GET method. This allows you to fetch a resource by its hash and, if the hash is a directory, by the path from that directory to a named file.

If you enable the Writeable flag for a gateway, it gains the ability to understand the HTTP POST, PUT, and DELETE methods. This allows clients to add data to IPFS, but doesn’t trust them with the full daemon API.

You can enable this mode by setting Gateway.Writeable to true in the daemon configuration, or by passing the --writeable flag on the daemon’s command line.

How do I Use a Writeable Gateway?

:exclamation: The gateway will not pin the resulting hashes of any of these operations. That’s your responsibility.

POST /ipfs/

This will ingest the uploaded file, and return its ID in an ipfs-hash response header.

DELETE /ipfs/QMHashGoesHere/path/to/file.ext

This will generate a new IPLD file tree resembling the one specified, but with the indicated file removed.

The new tree’s ID will be returned in an ipfs-hash response header.

PUT /ipfs/QMHashGoesHere/path/to/file.ext

This will ingest the uploaded file.

This will then generate a new IPLD file tree resembling the one specified, but with the ingested file added at the indicated path.

The new tree’s ID will be returned in an ipfs-hash response header.

:skull_crossbones: If the referenced file tree already contains an entry at the given path, this instead behaves like a POST, returning the hash of the added file, not the updated file tree.

I am 90% sure this is a bug, because I can’t see this behavior being useful. For now, it can be worked around by issuing a DELETE against the tree, then PUTing to the tree that DELETE returns.

PUT /ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn/file.ext

While you can upload bare files with POST, it’s often nicer to wrap them in an empty directory- to give them a filename, for example, or to easily PUT additional files alongside them.

QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn is the hash of the empty directory, so you can PUT a file to it to get that wrapper.

Example

https://ipfs.io/ipfs/QmWNXVTaYdDxoCXdP1w7hseJ3U5feH5tgvPxJ78c6dH3U2/script.js - the operating script for a styled pastebin that clones itself with the new text on save.

5 Likes

I am really interested in some form of REST API for Daemon / Gateway optimized for the client side in relation to the following exploration https://github.com/ipfs/in-web-browsers/issues/137

However I’m not yet sure what are set of requirements I’d like such an API to meet. I am working towards defining those requirements and would be happy to provide feedback here one I’m ready.

Also might be worth getting textile folks eyes on this, as I think there might be some overlap with their textile cafe nods that also expose higher level API.

2 Likes

I’m interested in the same, but am starting with something very basic, which basically takes a multipart file upload up to 10mb and then blasts this at a locally exposed writable API.

This is basically to ensure that the service will not be abused.

It’s all for https://blurt.world

BTW, here’s the code in case it’s useful to anyone:

Turned out that I needed to do this in Javascript anyhow because I needed to verify signatures that are tough to verify in Go.