[NEW CONTENT] Dweb addressing

[Mr0grog]

At the IPFS developer summit in Berlin in July 2018, we had poster-making sessions where people explored various IPFS concepts. We should expand on the DWeb Addressing poster by adding a doc in the content/guides/concepts folder.

This is a subtask of #56.

[Mr0grog]

In a different session at the developer summit, we talked about calling this concept a “content path.”

“Content path” is not a term that’s really been in much use, but folks were concerned about needing to identify the address of a peer or IPFS node from the address of a piece of content/a DAG node/IPLD node/UnixFS node. This was the best term we could come up with for the latter type of address (e.g. how IPFS does content-addressing).

We did not have time to write a rough draft, so this needs to be written from scratch.

---

Concept docs are concise, high-level descriptions of various core concepts in IPFS. They live in the content/guides/concepts folder and should strive to answer:

1. What is this?
2. How does it relate to the rest of IPFS?
3. How can (or should?) you use it? (Note: sometimes the answer is that you should understand it, but not use it. Bitswap is probably a good example.)
4. Where do you go to learn more?
5. What is the current state of affairs?

[lidel]

I created #118 as a quick short-term solution to point people at the memo with current best practices and conventions.

In the long term that link will be refined and moved to docs site as a guide with corresponding concepts pages for things like path-addressing, multiaddr, gateways and security considerations around URI/URLs.

I plan to make it an OKR for Q4 2018 In Web Browsers WG.

For now just linking some source materials and notes related to addressing (in chronological order):

• Background on Address Scheme discussions (dweb, ipfs:// and more) ipfs/specs#152: Background on Address Scheme discussions (dweb, ipfs:// and more)
• https://github.com/ipfs/specs/tree/master/dweb-addressing
  This is an outline and a lots of notes for long doc started by Lars..
• https://github.com/lidel/specs/tree/dweb-addressing/dweb-addressing
  ..I started expanding it to include browser contexts but in the process noticed multiple issues with the doc:
  • It tries to be too many things at once, ends up being too big to be easily digestible
  • Does not address immediate needs such as a short gist of best practices for developers
  • Was created before we had a proper docs site, at a time we had self-containing specs, even for things that should not be a single spec.
• https://github.com/ipfs/in-web-browsers/blob/master/ADDRESSING.md
  This is a memo with current URLs and URI conventions, created before DWeb Summit 2018.

[Mr0grog]

That sounds great! 👍

For what it’s worth, I think it would be helpful if the concept page version of this started by just covering the basics (maybe with a nice diagram pointing to the different parts of an example address):

• In IPFS, addresses (for content) are path-like; they are components separated by slashes.
• The first component is the protocol, which tells you how to interpret everything after it.
• Content referenced by a hash might have named links. (For example, a Git commit has a link named parent, which is really just a pointer to the hash of another Git commit.) Everything after the CID in an IPFS address are those named links.
• Since these addresses aren’t URLs, using them in a web browser requires reformatting them slightly:
  • Through the HTTP gateway, as http://<gateway host>/<IFPS address>
  • Through the gateway subdomain (more secure, harder to set up): http://<cid>.ipfs.<gateway host>/<path>, so the protocol and CID are subdomains.
  • Through custom URL protocols like ipfs://<CID>/<path>, ipns://<peer ID>/<path>, and dweb://<IFPS address>

That might feel a bit basic (especially the first three parts), but we don’t really have one clear place where we just say it. It would be helpful for new folks.

[jessicaschilling]

Closing this issue, since many concepts have been integrated into the content in https://github.com/ipfs/ipfs-docs-v2/edit/master/docs/how-to/address-ipfs-on-web.md.