http-api-docs vs. ipfs/specs. vs. interface-js-ipfs-core

[daviddias]

I believe this will be really confusing for users, right now we have:

• https://github.com/ipfs/http-api-spec
• https://github.com/ipfs/ipfs-http-api-docs
• https://github.com/ipfs/specs/tree/master/public-api/http

Does anyone know the de decision behind?

[daviddias]

Apparently https://github.com/ipfs/http-api-spec should not be trusted anymore as it is clearly way out of date

[ghost]

Apparently https://github.com/ipfs/http-api-spec should not be trusted anymore as it is clearly way out of date

I feel like we can empty that repo. We should also somehow remove the apiary site: http://docs.ipfs.apiary.io -- likely need a login?

https://github.com/ipfs/ipfs-http-api-docs

This is a tool for generating API docs from go-ipfs's ipfs commands output. In my opinion it should be merged into go-ipfs, in a scripts/ or tools/ directory.

[ghost]

I feel like we can empty that repo

Or maybe not empty it, but rename it to apiary-experiment or so.

[Mr0grog]

@lgierth do you still think this belongs in ipfs/go-ipfs or should it be in ipfs/docs now? Either way, it does seem like some consolidation would be nice.

Relatedly, do you know what builds the existing commands docs (if anything)? They claim to be generated, but then they were hand edited later.

It seems clear that both could use some serious improvement, so I’m trying to figure out the right technical way forward so I we know how/where to make content changes.

[Mr0grog]

do you still think this belongs in ipfs/go-ipfs or should it be in ipfs/docs now?

Or a third option: ipfs/go-ipfs-cmds? If I understand correctly, that is replacing all the commands code in ipfs/go-ipfs, right?

[Kubuxu]

ipfs/go-ipfs-cmds is just a library code, commands are still defined in go-ipfs

[Mr0grog]

Ah, ok. I had thought ipfs/go-ipfs-cmdkit was the abstract library and ipfs/go-ipfs-cmds was going to be the actual IPFS commands. Thanks for clearing that up. Any thoughts on how we can/should better clarify the relationship between all three in readmes, etc?

Also, is there a relatively easy/quick path to fixing the code here and/or moving it into either ipfs/go-ipfs or ipfs/docs? Trying to understand whether we should just focus on making manual improvements to the API and command docs for now or do something else.

I think it’s also an open question as to whether automatic doc generation for this is the right path; at least one person I talked with had lots of trouble getting much useful out of them and, when shown the docs at interface-ipfs-core, were blown away by how much more helpful they were, even if they don’t specifically cover how they translate into HTTP requests.

[nothingismagick]

interface-ipfs-core

Wow. Just like - wow. Why isn't this plastered everywhere across the internet? And its mocha-based! I was feeling a bit depressed, but this just made my day.

It seems though, for example that some parts of the key spec are implemented in node.js but not in go... I thought go was feature complete and node was lagging behind - but I will actually be only developing in the node environment, so whatever... Just, does this influence the docs in any way?

[Mr0grog]

The more I look at this, the more inclined I am to say these docs should actually be manual (we might use these generated docs as a seed to start from, though). Some of the HTTP APIs are pretty straightforward, but other ones are significantly more complex than their command-line variants. The simple cURL example for adding a file, for example, is not nearly clear enough — it really needs to describe the expected headers for each part of the multipart parts; who’s going to know to look at this JS code or this Go code to find it, and even then, fully understand how to format it?

One alternative might be add a second field to the Go help text, so you have both LongDescription and HttpLongDescription or something.

[hsanjuan]

For anyone susceptible of reading the above and trying to do Apiary or Swagger, I wasted a fair amount of time back in the day and there was no way for those REST-API spec languages to accommodate what is not a REST API, so you end up with the same problem set as right now.

add is the main problematic endpoint that people have trouble with but the rest 99% is actually pretty nice and usable. We can write add manually if need be. Generating the docs automatically from go-ipfs not only produces very accurate results of what the API takes and gives, but gives a very good diff of changes between versions and pointers of places where go-ipfs needs to improve.

For me these are quality docs, simpler, easy to scroll through, to search, to patch if needed by just fixing go-ipfs sources directly. The people that come to these docs, get what they need, and move on with their lives because they found how to call an endpoint do not open issues to voice out support like those that get confused over the /add endpoint.

What we should probably do is to have js-ipfs-api docs in the ipfs docs website too (but that is out of the scope of this repo, which is to generate docs for go-ipfs).

[lidel]

Closing – repos mentioned in the top comment are no longer relevant (#48)

We now have HTTP/CLI API docs automation introduced in ipfs/ipfs-docs#875 – example in ipfs/ipfs-docs#887