Document the HTTP Gateway features and functionality for developer users

[autonome]

There's a few features here:

https://github.com/ipfs/go-ipfs/blob/master/docs/gateway.md

We also get questions often like "how can i get a directory listing?" or "can i publish through the gateway?".

[autonome]

Should also have a section that clearly disambiguates the HTTP Gateway and features with the HTTP API

[johnnymatthews]

This could just be a case of copying that Gateway doc over into this repo. I've slapped the need/analysis tag on here; someone from the docs team should find out exactly what we need here.

[autonome]

That'd be a start, but it's quite sparse right now. I want comprehensive documentation and a guide to usage, with examples.

…

On Mon, Mar 22, 2021 at 10:48 AM Johnny ***@***.***> wrote: This could just be a case of copying that Gateway doc over into this repo. I've slapped the need/analysis tag on here; someone from the docs team should find out exactly what we need here. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#708 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAMHN2LMQMUIRF5PS3XPN3TE5KFNANCNFSM4ZQWKD7Q> .

[lidel]

Gateway specification is published:

• https://github.com/ipfs/specs/tree/main/http-gateways#readme

and we now have separate pages about Kubo RPC and HTTP Gateway APIs:

• https://docs.ipfs.tech/reference/http/api/
  • https://docs.ipfs.tech/reference/http/gateway/
  • https://docs.ipfs.tech/reference/kubo/rpc/

It is a good time to update Gateway content on docs.ipfs.tech. Mainly, there is also a bit outdated https://docs.ipfs.tech/concepts/ipfs-gateway/ which needs to be rewritten.

Main pain points:

• lacking "best practices" section
  • using subdomains for origin isolation
  • when running an open public agteway, use a separate, dedicated domain name, to limit blast radius described in https://nft.storage/blog/post/2022-04-29-gateways-and-gatekeepers/ (link to it as a warning?)
• describes "writable gateways" which are not specified, we only have old experiment in Kubo which should not be listed in public docs
• does not mention subdomain gateway examples: dweb.link (PL) and cf-ipfs.com (Cloudflare)
• "Authenticated gateways" section shows /api/v0 as "gateway" – should be removed entierely
• "Resolution style" and "Gateway services" duplicates content from "path", "subdomain" and "dnslink" sections at https://docs.ipfs.tech/how-to/address-ipfs-on-web/
• "Delay-sensitive applications" does not mention IPNS over PubSub for close-to-real-time updates
• "End-to-end cryptographic validation required", "Misplaced trust", "Gateway man-in-the-middle vulnerability" sections were created long time ago and are outdated. We now have trustless responses (block and car, described in https://docs.ipfs.io/reference/http/gateway/#trusted-vs-trustless) – all these sections should be replaced with a single "Delegated trust vs Trustless gateways" section based on #trusted-vs-trustless
• "Assumed filenames when downloading files" xshould be replaced with "parameters" section that includes filename, download and format parameters
• "Stale caches" is ok in theory, but Kubo Gateway will cache /ipns/ resolution for 1 minute – this should me mentioned in ::: callout block
• FAQ section should mention both ipfs.io AND dweb.link and suggest people should use the latter
• "Who is responsible for the content that is viewed through the ipfs.io gateway?" should link to https://ipfs.io/legal/
• (loose idea) perhaps there should be a separate page about ipfs.io and dweb.link. we should not mix the concept of gateway with the centralized service sponsored and provided by Protocol Labs