docs: add HTTP API v1 spec

[achingbrain]

This PR adds a spec for the /files path as a REST resource. It's a little different from what we have right now but is closer to the kind of conventions a developer fresh to IPFS would expect to see having worked with other HTTP APIs in the past.

It covers pretty much all of the regular files API and MFS operations and could be viewed in conjunction with ipfs-shipyard/ipfs-http, FILESv2.md and ipfs-shipyard-ipfsx. Also Writeable HTTP Gateways, though the intention of this is only to orchestrate locally running nodes, not to expose full remote functionality.

It also has the added benefit that errors in streams will work in the browser (see ipfs/js-ipfs#2519).

[Stebalien]

I've opened an issue to discuss using RPC instead of REST. Let's keep that discussion to that thread so this thread can focus on this proposal.

[lidel]

This feels like a reminiscent of "writable gateway" feature, which reused HTTP's POST/PUT/DELETE semantics for importing and manipulating data via "invisible api" exposed on Gateway port (What is a Writeable Gateway? / Is there any public writable gateway?). The key feature of writable gateway was its simplicity.

If we frame this proposal as extending Writable Gateway feature, then tightly coupling it to HTTP semantics makes sense, as long we use safe defaults and avoid obscure features. I think all operations should work with curl alone. Switching examples to curl would help in keeping that in check.

ps. big 👍 for fixing status codes

[lidel]

I was about to suggest dot notation for clear namespacing (application/ipfs.unixfsv1.file), but then remembered media-types at IANA are a mess anyway :^) So its just a subjective decision I think.

[achingbrain]

Completely subjective. I prefer concise kebab notation over dots because weird overly-specified mime types like application/vnd.ms-word.document.macroEnabled.12 give me the twitchy eye.

[lidel]

Don't think I've seen content-disposition in requests before this: are we repurposing response-header here?

ps. having both application/directory and application/ipfs-unixfs-v1-directory in API docs looks messy, but don't see how we can avoid it :(

[achingbrain]

I'd taken inspiration from it's use in multipart/form-data requests (rfc7578).

[achingbrain]

My thinking is that application/directory is an input type and application/ipfs-unixfs-v1-directory is an output type.

[lidel]

Loose idea: does it make sense to require use of URI-encoded filename* by default, to save time on bug reports about broken filenames?

Context: that is what js-ipfs and go-ipfs already do for content-disposition in response, triggered via ?filename= (example), check via CURL:

$ curl -Is "https://ipfs.io/ipfs/QmUwrKrMTrNv8QjWGKMMH5QV9FMPUtRCoQ6zxTdgxATQW6?filename=250px%D9%8A%D9%88%D8%B3%D9%81_%D8%A7%D9%84%D9%88%D8%B2%D8%A7%D9%86%D9%8A_%D8%B5%D9%88%D8%B1%D8%A9_%D9%85%D9%84%D8%AA%D9%82%D8%B7%D8%A9_%D8%A8%D9%88%D8%A7%D8%B3%D8%B7%D8%A9_%D9%85%D8%B1%D8%B5%D8%AF_%D9%87%D8%A7%D8%A8%D9%84_%D8%A7%D9%84%D9%81%D8%B6%D8%A7%D8%A6%D9%8A_%D8%AA%D9%88%D8%B6%D8%AD_%D8%B3%D8%AF%D9%8A%D9%85_%D8%A7%D9%84%D8%B3%D8%B1%D8%B7%D8%A7%D9%86%D8%8C_%D9%88%D9%87%D9%88_%D8%A8%D9%82%D8%A7%D9%8A%D8%A7_%D9%85%D8%B3%D8%AA%D8%B9%D8%B1_%D8%A3%D8%B9%D8%B8%D9%85._.jpg" | grep -i content-disposition

[achingbrain]

Sounds good

[achingbrain]

I've added notes about this. I'd like to preserve the / character as a separator but have stated that individual path components should be URI encoded.

[lidel]

Below this, I'd add positive example of fetching directory as a TAR archive. It is already implemented in API v0 (example: .tar / .tar.gz).

Digression/small problem: TAR archives have no official media type registered at IANA ;^) People suggest using application/x-tar and application/gzip respectively but its not in any spec AFAIK.

[achingbrain]

Done. The problem with application/gzip is it doesn't tell you what's in the archive. We could just use application/x-tar and let the transport layer handle the gzipping but it's probably not what people would expect.

[achingbrain]

This feels like a reminiscent of "writable gateway" feature

I think this solves a slightly different problem to the one I'm trying to solve, but it's vaguely similar so I've added it to the prior art-type section in the description.

I think all operations should work with curl alone. Switching examples to curl would help in keeping that in check.

I agree they should not require a complex toolchain to try out locally, but I'm wary of letting curl's interface influence our API so would rather not do that in the spec. Once this is agreed there's nothing to stop us having interactive docs in the future that do use generated curl examples.

[hacdias]

Considering we now have the HTTP Gateways, and IPFS implementations no longer follow the same RPC API, I am closing this PR. Feel free to re-open if for some reason if feels relevant.