Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the HTTP Gateway features and functionality for developer users #708

Closed
autonome opened this issue Mar 20, 2021 · 10 comments · Fixed by #1531
Closed

Document the HTTP Gateway features and functionality for developer users #708

autonome opened this issue Mar 20, 2021 · 10 comments · Fixed by #1531
Assignees
@ElPaisano
Labels
dif/medium Prior experience is likely helpful effort/hours Estimated to take one or several hours kind/maintenance Work required to avoid breaking changes or harm to project's status quo kind/suggestion Something that you'd like to see in the docs. This can be written content, web design, or imagery. need/analysis Needs further analysis before proceeding status/ready Ready to be worked topic/docs Documentation

Comments

@autonome
Copy link
Contributor

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 autonome added need/triage Needs initial labeling and prioritization kind/suggestion Something that you'd like to see in the docs. This can be written content, web design, or imagery. labels Mar 20, 2021
@autonome
Copy link
Contributor Author

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

@johnnymatthews johnnymatthews added dif/medium Prior experience is likely helpful effort/hours Estimated to take one or several hours kind/maintenance Work required to avoid breaking changes or harm to project's status quo need/analysis Needs further analysis before proceeding P3 Low: Not priority right now status/ready Ready to be worked topic/docs Documentation labels Mar 22, 2021
@johnnymatthews
Copy link
Contributor

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
Copy link
Contributor Author

autonome commented Mar 22, 2021 via email

@johnnymatthews johnnymatthews removed the need/triage Needs initial labeling and prioritization label Apr 22, 2021
@lidel
Copy link
Member

lidel commented Aug 8, 2022 •
edited

Gateway specification is published:

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

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
  • 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 lidel added P1 High: Likely tackled by core team if no one steps up need/triage Needs initial labeling and prioritization and removed P3 Low: Not priority right now labels Aug 8, 2022
@lidel
Copy link
Member

lidel commented Aug 8, 2022

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

@johnnymatthews
Copy link
Contributor

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
Copy link
Contributor

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

@TMoMoreau TMoMoreau self-assigned this Aug 17, 2022
@TMoMoreau TMoMoreau removed the need/triage Needs initial labeling and prioritization label Oct 6, 2022
@ElPaisano
Copy link
Contributor

@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 ElPaisano assigned ElPaisano and unassigned TMoMoreau Mar 30, 2023
@ElPaisano ElPaisano removed the P1 High: Likely tackled by core team if no one steps up label Apr 3, 2023
@ElPaisano
Copy link
Contributor

Removing P1 label unless I hear back from the team

@ElPaisano ElPaisano linked a pull request Apr 11, 2023 that will close this issue
Update gateways info #1531
Merged
@ElPaisano
Copy link
Contributor

Based on #1531, closing this

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ElPaisano ElPaisano

Labels
dif/medium Prior experience is likely helpful effort/hours Estimated to take one or several hours kind/maintenance Work required to avoid breaking changes or harm to project's status quo kind/suggestion Something that you'd like to see in the docs. This can be written content, web design, or imagery. need/analysis Needs further analysis before proceeding status/ready Ready to be worked topic/docs Documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Update gateways info ElPaisano/ipfs-docs
5 participants
@autonome @lidel @johnnymatthews @TMoMoreau @ElPaisano