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:
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.
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.
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!
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.
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?
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
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?
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
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
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
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
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.)