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

[lidel]

@johnnymatthews @2color i'm around to brainstorm / review if anyone has bandwidth to work on this

[johnnymatthews]

Unfortunately, I don't have any time to work on this right now. But @TMoMoreau might be available to work on this, if you're able to give some guidance @lidel?

[TMoMoreau]

I should be able to get to this once I'm done with documenting the _redirects stuff.

[ElPaisano]

@autonome docs team is triaging old issues like this one. We've made afew changes to existing gateway info in the docs in the last few months, plus #1531 (currently in review) updates alot of our gateway documentation. Could you take a look at said PR, let us know what you think, and then we can add in any missing information based on this issue request? Or, if you're not available to review, could you please suggest someone who can assist? Thank you :)

[ElPaisano]

Removing P1 label unless I hear back from the team

[ElPaisano]

Based on #1531, closing this