Document the HTTP API

[daviddias]

We've been getting several questions about how the HTTP API works, it would be good to have a way to auto generate some docs for it.

@whyrusleeping @jbenet can you add the 'help wanted' label plz? @RichardLitt was interested in helping with this

[jbenet]

@RichardLitt see #785

take a look at:

• https://stripe.com/docs/api
• https://www.dropbox.com/developers/core/start/python
• http://readme.io/ <-- could use this, too
• https://www.quora.com/Which-companies-have-the-best-developers-website-and-API-documentation

This would document both the HTTP API and the CLI API.

• the cli api is available with ipfs --help and here ipfs.io/docs/commands
  (generated by https://github.com/ipfs/website/blob/master/src/ipfs.io/docs/commands/Makefile)
• the HTTP api is stubbed here: ipfs.io/docs/api but it matches the cli one.

[jbenet]

maybe we should move this discussion to another repo, called ipfs/ipfs-node-api or ipfs/node-api ? (we could put tests there, too)

[stadja]

Hello :)
I am interested too on how does the http-api work !

How can I help ?

[gr0uch]

+1, I wasn't aware that there is an HTTP API until I found this issue :)

[jamescarlyle]

Interested in helping

I can't get the API to work in a way that I expect, i.e. this CLI command

echo '{ "Links": [],"Data": "\u0008\u0002\u0012\u000chello world\n\u0018\u000c"}' | ipfs object put

should map to http POST to
http://localhost:5001/api/v0/object/put with the payload as the {Links, Data} block above

but I get back a 400 with "File argument 'data' is required"

[RichardLitt]

@jbenet Thanks. Been taking a look at those - pinged one of the cofounders of Readme.io in #785. I hope we can get Readme.io working automatically, it looks like it's all manual markup, which would not be ideal.

maybe we should move this discussion to another repo, called ipfs/ipfs-node-api or ipfs/node-api ? (we could put tests there, too)

I'm confused - how would this be the node-api? Isn't that the function of ipfs/node-ipfs-api?

[jbenet]

@RichardLitt sorry, the word node there meant an ipfs-node, not node.js. sigh confusion. maybe just ipfs/ipfs-api or even ipfs/api then.

[RichardLitt]

Let's move this to another repo, I think there's a few different strands that should have their own discussions and space to grow.

Going to do that now, see if I can get the Readme parser working while I do it.

I started this awesome-docs repo to start crowdsourcing the best documentation practices, examples, and resources. Surprised it didn't exist already.

[RichardLitt]

This has been solved. See ipfs/api and https://github.com/ipfs/specs/tree/master/api.