Define an IPFS Core API spec & adopt interface across impls

[hackergrrl]

Goal

Having a well-defined specification for the IPFS Core API will let us build JS, Go, etc. modules that define the core interface, allowing many different implementations. This is very important for IPFS App developers: rather than hard-code for an HTTP daemon or a Go ephemeral node or a localhost daemon, they can simply develop against the Core API and swap out IPFS Nodes as needed. This will be especially useful once js-ipfs runs in the browser and apps will want to swap between HTTP and a local node.

Steps

• meeting with at least @jbenet @diasdavid @whyrusleeping to discuss core spec
• update the core spec with API details (use go-ipfs as a base)
  • ongoing work here: ipfs/interface-ipfs-core
• write a JS ipfs-core-api module that exposes the core interface (with tests)
• update js-ipfs core to adhere to ipfs-core-api
• update js-ipfs-api asking that it adhere to the ipfs-core-api
• write a Go ipfs-core-api package that exposes the core interface (with tests)
  • Gateway uses minimal IPFS Core API kubo#2876
• update go-ipfs-api to adhere to ipfs-core-api

Steps updated by @lgierth 1-Sep-2016

[daviddias]

In addition to the list advantages, having this kind of spec will create good documentation of the several subsystems present inside IPFS, by documenting their entry points.

Agreed with all the steps listed :)

[RichardLitt]

Also agreed. What sort of API details do you mean for the core spec?

[hackergrrl]

I'm glad you asked. 😀

Right now the core spec doc only lists method names. We should fill in the API method signatures and their semantics. You've done similar work in solidifying the HTTP API, right @RichardLitt? Would love to get your thoughts!

[RichardLitt]

I agree entirely. Give me a syntax and I'll give you a stab. 🔪

[hackergrrl]

I don't know of any language-agnostic API specification formats, so I'd personally be inclined to write something Node-like for v1, but generalize out the language-specific bits (like callbacks vs sync methods, opts objects, etc).

[dignifiedquire]

I think it should be based on a language with a good type system, haskell and rust come to mind, go types would work as well or if you want to keep it javascripty you could use typescript or flowtype.

[hackergrrl]

To avoid bikeshed, whoever writes the doc should probably just use the format that feels most comfortable to them. 😀

[lamarpavel]

As an example, the API spec of OpenGL (and now also Vulkan) are using C syntax as it is common to most programmers and can be seen as somewhat neutral ground. Making it understandable to most programmers could be more important than making it look elegant.

[daviddias]

++ @jbenet @whyrusleeping

https://github.com/ipfs/specs/tree/master/api/core

[hackergrrl]

Good reference from @dignifiedquire: https://github.com/ipfs/js-ipfs-api/blob/feat/files-api/API.md

[hackergrrl]

@jbenet @diasdavid @whyrusleeping (and anyone else interested): let's set a time in the near future to do a hangout on the core spec (this issue).

Could you share your availabilities here? I know the next week is going to be busy, but maybe we could do it in person in Berlin and also stream it as a hangout to the rest of the community. Please share your thoughts here.

[RichardLitt]

I'm free next week. I want to be there for this.