Clarify the different APIs

[flyingzumwalt]

Update the documentation to clarify how are these related

• http api
• core-interface (aka common interface)
• etc.

Put that info into the main landing places where people seek API documentation (ie. https://ipfs.io/docs)

[daviddias]

Currently, we have API descriptions in 3 places:

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

Only https://github.com/ipfs/interface-ipfs-core provides tests to ensure that the implementation is compliant with the spec.

The http-api needs more than just documentation and tests, it needs to be fully revisited to remove the current limitations: https://github.com/ipfs/http-api-spec/issues/116

As for the CLI API, we have sharness tests, but no real spec. One of the things that comes often is to break the sharness tests in its own repo so that they can be run against any CLI implementation, we could call it interface-ipfs-cli.

[Mr0grog]

@diasdavid @whyrusleeping Just to clarify, I know go-ipfs and js-ipfs are generally aiming for parity, but is it right to say that:

• The HTTP API and the CLI API for each should be exactly the same? (Obviously they may be slightly different in practice because work won’t be done at the exact same time, there are bugs, etc., but any differences should generally be a bug.)

• Their library interfaces will necessarily have some different types, constructors, helper methods, etc., but we also expect each will have a same core set of functions that correspond to each of the above HTTP/CLI commands and does roughly the same thing with similar options and arguments?

[whyrusleeping]

@Mr0grog The HTTP apis should be exactly the same. The CLI's in my opinion don't need to be, theres really no reason for js-ipfs to have a CLI other than for testing (look at all the effort we've spent making a nice CLI program in go ;) )

We're working on a 'coreapi' that should be roughly the same between the two languages, at least in structure. Other library interfaces should be similar, and in general we are aiming towards having the same structural layout where that makes sense.

[dryajov]

Hehe... interesting statement regarding js-ipfs. If the main aim of js-ipfs is not the CLI (which I agree with), why have one at all then?

[Mr0grog]

I’m going to close this as complete for now:

• We’ve got reference docs for all of these listed side-by-side at https://docs.ipfs.io under “Reference → Commands & API.”
• The introduction to the HTTP API now attempts to explain how the CLI, HTTP API, and core APIs relate.
• In both the Go overview and JS overview, we attempt to explain the different between *-ipfs (core) and *-ipfs-api (http).

There are undoubtedly more places we could hit these concepts and explain more (e.g. #60), but I think we’ve covered this from the big-picture perspective. We should open specific issues for any specific shortcomings we have/improvements we should make.

Please comment if you think we should re-open.