Are these seriously the docs?

Help
1

So, it’s basically impossible to learn how to write code that uses IPFS from just these docs without also using them. I was hoping the CLI client would work in a similar way so I could at least see what the response fields are so maybe, if I just had an example that made sense, I’d understand what I’m looking at.

Here’s an example. Nah, examples are so boring. Let me tell you a STORY. Also, I had to put all the links in IPFS, so when you see IPFS hashes, the links are in IPFS and so just load those up to get the actual links. To find out why I had to do something so silly, keep reading, because the story is even sillier than that, if you can believe it…

I wanted to go with the full-featured approach in Rust, which means, using the ipfs_api crate, which makes calls to go-ipfs over HTTP. And then I want to get IPFS to add some bytes for me. So I look at the docs. Docs.rs is awesome, it’s one place where you can go and find all the docs. But that’s when things get weird.

I want to understand what the response fields are after doing an IPFS add. So, after going to this documentation:

QmNnwNryHCkMbvAdhFXdVPQ6NWE6ir1hNwBRaEDRoqG6WM

Wait, what. What’s the difference between a name and a hash? Like, how does it get a “name” from just some bytes I give it?

So, I try to find the original documentation.

QmUuoYhF21Uzm9iqp5ta6pGs1cA2GPRLoU7sTfrPXE2e4o

Wait, what? Where’s the docs? IPFS has been around for years and years and years? At least five years, right? Is it not mature now?

reads down a bit Oh! Here they are, okay. Should just get rid of that page, then. Maybe just kill the repo, like, why have it? Sorry, Mario, your docs are in a different repo.

QmQtuAeEXmBFxzLxyzwRcctvYZsjRsAvu4apedLveUuP6u

Wait, this isn’t docs. This is the repo that makes the docs? How do I get to the docs from here? http-api-docs is just Go files. I don’t read Go, I read English.

goes back to README, reads it more Oh! HERE are the docs!

QmZ9K696jQdgBPKKV4VfxPqcVTrEFJkes6rpNnTsgj7E12

Yes, okay, okay, let’s see here, the add method, yep. Arguments looks… comprehensive. Not sure what the default is if some of these things aren’t required, though. Like, if I don’t provide the trickle argument, since it’s optional, is it still inserted as a trickle-dag? Wait, what? Nevermind, nevermind, that’s not the response body question I had earlier. Let’s answer that question.

scroll scroll

QmR4ujXr9jC2qrVj8pgUiwubgxy11b5k7PQTxTnf226QGU

Wait, what? Why are there four fields here, and in the Rust API it’s only three?

Oh, I see, the bytes are left out in the Rust version, since I just gave it a Vec of bytes, I can easily just call len() on that Vec if I wanted its size, I guess… And yes, an int64 is a reasonable data type for that, that baby holds 18 exabytes right there, myes it does!

Okay, so, now, what’s the difference between a name and a hash?

Wait, what. They’re just strings. That’s no more informative than the other docs. A base64-encoded image is just a string. An email is just a string. A SQL query is a string. IDK, if you’re such a string expert, name every string.

This doesn’t answer my question. How does it get a “name” for my bytes? Hash makes sense. I understand what a hash function is. It can make a string out of any bytes I give it, so cool! But… a name function??? Gives me names? Random ones? Or ones from a particular language? Are they vulgar names? Haha, I’ll bet they are. You IPFS devs are so naughty. Anyway, okay, these must not be the official OFFICIAL docs. This is a dead end. I’ll just go to IPFS.com. Wait, what? Oh, no, not THAT IPFS. Okay, IPFS… ipfs.io. Yes, this one.

Here we are. Docs. API & CLI docs, yes. The HTTP API, yes. Oh, these look familiar. Wait, what?

QmP3TELH5YqJhxprY4sv6btdBTJh4GmZR687eBLA5TYQdi

These can’t be the same ones, can they? CAN THEY!?!?!? Ugh.

Okay, so, maybe if I just run the CLI client, it’ll give me something similar to what the actual API response should be. I read somewhere that the CLI is just a thing that interacts with the HTTP API.

Fuck it. In my terminal where I run cargo and git stuff, and I’m feeling silly so I run cargo add README.md. Because, screw it, just give me the response.

added QmagMMqhevrGertc35kg1yYHnnz2XJMntZ6sg1LsF165Ht README.md

Huh. None of this is labeled. It has even LESS information than the original response! But I’m guessing one of these is the hash and the other is the name. Am I to assume I get an empty string if I just add some bytes? I mean, I guess that makes sense in JavaScript, since empty string also means null. Or is it undefined? Eh, anyway. Well, if that’s what that is, then where’s the size?

Maybe there’s a way for this to label the fields in the response, it’s not giving me enough information. Is there a verbose option?

ipfs add

NO DON’T ADD ALL MY STDIN. ctrl-C, ctrl-C. Ugh.

ipfs add --help maybe?

Uh huh, uh huh… Verbose option? No, but there’s a quiet option. No default specified, so I’ll just set that to false, maybe it’ll make it verbose.

ipfs add --quiet=false README.md

That’s no different than before! The quiet option makes it give even LESS information? I don’t see how…

Oh, that just gives me the hash. Huh. Multihash is so weird, haha. Hope that’s not something silly like MD5… Or SHA-1? Eh, focus, focus…

Okay, where do I go from here? Oh, you know what, I remember seeing a Curl request earlier somewhere… Let’s go find that… Okay, official docs, this better work…

`url -X POST -F file=@myfile "://127.0.0.1:5001/api/v0/add?quiet=&quieter=&silent=&progress=&trickle=&only-hash=&wrap-with-di

rectory=&chunker=size-262144&pin=true&raw-leaves=&nocopy=&fscache=&cid-version=&hash=sha2-256&inline=&inline-limit=32"`

curl: (26) Failed to open/read local data from file/application

Oh right, here, here.

`curl -X POST -F file=README.md "://127.0.0.1:5001/api/v0/add?quiet=&quieter=&silent=&progress=&trickle=&only-hash=&wrap-w

ith-directory=&chunker=size-262144&pin=true&raw-leaves=&nocopy=&fscache=&cid-version=&hash=sha2-256&inline=&inline-limit=32"`

could not convert value "<value>" to type "int" (for option "-cid-version")

Uhhh… Oh, I see what this is. That’s silly. I’m just gonna toss all of these. Let’s hope there’s some sensible defaults… Okay, here, let’s try this:

curl -X POST -F file=README.md "://127.0.0.1:5001/api/v0/add

Ugh, JSON. Pipe that gunk to jq. Ugh, that other weird loader bar junk is annoying. Wait, what? Only three fields! This matches what I saw on Docs.rs! Are the Rust docs better than the official docs???!?!? Imagine that. Everything’s better in Rust. Hope that Rust rewrite is going well. Not sure what the difference is betwee ipfs-rust and rust-ipfs is, but I like what this guy is doing with sled, which is obviously the superior key value store, so I can just embed the node instead of bundling ipfs-go with my app. Sigh, it still doesn’t do everything I want it to do and every time I go to mess with it I can never get the example code working, but hey, at least the README on ipfs-embed is a lot bigger than it used to be. I like these decisions a lot, actually! Blake3 is such a modern algorithm, how progressive. He’s using nQUIC too? Maybe? Libnoise is cool too. Screw that OpenSSL garbage, haha. Anyway, damn, I’m on such a tangent… Okay, screw it, I give up, guess I’ll just toss this on the forums and call it a night, maybe I’ll have some fresh ideas in the morning. Still wish I knew the difference between size and bytes, though. Like, what could possibly be the difference? (Spoiler: it’s human-readable, like, if you provide the h option to ls. And wait, what? It’s been hiding there next to that annoying loader bar this whole time!?!?!?!?! Ugh, y’alls are so weird.)

Oh, one more thing. These forums keep crashing my browser, is there any other place I can ask questions like this? I installed 64GB of RAM specifically so I could keep my browser open for as long as I want as long as I don’t go to buggy JS-heavy websites… Sigh, forums used to be SO MUCH BETTER when they were just written in PHP. You could patch the code and make it like an RPG, too, haha, fun times… Okay, no preview feature. Guess that would’ve been too much extra JavaScript. Create Topic… And… wait, I’m only allowed to post only two links at a time!? Okay, fine, I’ll encode the URL strings because I don’t wanto have to figure out what kind of STRING it thinks an HTTP URL is without it also violating the IPFS Forum Laws or whatever. Y’alls are such cops. Sigh, this’ll be fun… Oh wait! The IPFS CLI reads stdin! This’ll be great! I can just put the links on IPFS! YES!! Shit, will I have to keep this daemon running this whole time? Anyway… Time to get to work. There, done. Posted. Wait, what? Okay, fine, fine, screw it, I’ll just take the http part out of all these commands, shit. I hate these IFPS Forum Cops. Okay. Phew. All done. What a goddamn shitshow.

2

BTW, if this helps, here’s a screenshot of all the links.

Screenshot from 2020-12-08 22-57-03
Screenshot from 2020-12-08 22-57-031355×241 72 KB

3

Hi, I bumped your trust level so that you can post links.

These forums keep crashing my browser, is there any other place I can ask questions like this?

The API docs are autogenerated. The response type definition may have a name field, but that may be skipped from the API responses and only filled-in by the CLI when processing those responses (I suspect, I’m not sure). In that case, the name will be set to the name of the file you added (i.e. README).

Or maybe, because I’m speculating, the name is set to the name you send in your multipart request headers, as the documentation mentions, and it is not sent-back when it’s unset:

Content-Disposition: form-data; name="file"; filename="folderName%2Ffile.txt"

Verifying this hypothesis should be easy. You can always tcpdump what ipfs add does and whether name comes back or not.

4

Let’s start with the original question you had: What is the difference between “Name” and “Hash”

Hash is the CID (Content ID) of the file as you would access it via /ipfs/$CID.

It looks like the “Name” field is a passthru from the request. In the documentation at https://github.com/ipfs/ipfs-docs/blob/master/docs/reference/http/api.md#response…

Abspath: /absolute/path/to/file.txt
Content-Disposition: form-data; name="file"; filename="folderName%2Ffile.txt"
Content-Type: application/octet-stream

...contents...

…it looks like the “Name” parameter is the contents of the “filename” provided to the API here in the Content-Disposition field. I say “looks like”, because the documentation is generously described as incomplete in this regard and I was forced to dig thru the source code to get some idea of what go-ipfs was actually doing. I have to leave for work myself in a couple minutes, so I won’t be able to get back to this before 10 hours from now.

As to the generally bad state of the documentation, unfortunately, this is pretty standard for open source projects. Such projects attract programmers in spades, but not the technical writers needed to write coherent and complete documentation. The open source projects that have good documentation almost all have corporate sponsorship and can hire a full-time technical writer to work on the documentation while mostly leaving the programmers to program.

5

Actually we (Protocol Labs) could do that. If you know someone send them over. It turns out that having the skills to write coherent and complete documentation about IPFS tech (and wanting to do it) is not super easy. https://jobs.lever.co/protocol/93b4c25e-4ab2-482d-bda6-0b70202c038b

6

Unfortunately, I do not know any technical writers that are looking to change jobs. If I come across one, and they seem interested, I’ll point them to Protocol Labs.

I plan to submit an issue for this particular documentation problem once I am off work and find the right repository so that this gets resolved eventually.

7

Maybe around here https://github.com/ipfs/http-api-docs/blob/master/markdown.go#L229

(Protip: PR improving the text would be nice).

8

Issue No explanation of response fields #39 opened to track the documentation issue. Next is to figure out what changes need to be made to the document generator and then add the missing information and generate the required pull requests.

@cryptoquick has also opened a pull request to add a link to the actual documentation location: https://github.com/ipfs/http-api-docs/pull/38.