Core API needs to take flexible inputs

We've layed the groundwork for the Core API in go-ipfs by implementing parts of the Unixfs API. Its functions properly return CIDs, but they only accept path strings as arguments, which requires unneccessary conversions in most situations.

Core API functions should accept:

• CIDs
• Strings
• Multihashes
• Paths
• ipfs.io URIs

The go-cid package in use provides Parse() which takes care of it.

[hsanjuan]

I don't know if I understand this very well.

I don't like APIs which take interface{} but where interface{} means you can pass different representations of the same *cid.Cid thing but not absolutely anything. I find it very anti-Go in spirit. It makes go behave like Python. Helper methods like cid.Parse() are always available to facilitate that the user adapts to a c *cid.Cid parameter type, but we shouldn't make it an c interface{} type just because it saves a line somewhere else. Is that what you mean?

Note also that methods definitions are pretty much all the documentation we provide in many places, so they should be very meaningful (specially for a Core API).

[Kubuxu]

I agree with Hector, behaviour of CoreAPI should be as strict and as well defined, as possible (so we don't replicate mistakes from HTTP API). CID as being able to describe all of those protocols seems the best.

I don't know if we should limit it only to /ipfs/CID which would define the behaviour even better but would add additional resolve step for consumer of API but it means it is explicit and the consumer can decide if he wants to resolve IPNS for example.

You're both raising fair points.

CID as being able to describe all of those protocols seems the best.

No, we also need to somehow accept full-fledged paths like /ipfs/Qmfoobar/one/two/three and IPNS paths like /ipns/Qmfoo/bar and /ipns/example.com/foo/bar. I guess js-ipfs-api didn't have to deal with IPNS paths yet? cc @diasdavid

---

What do you think about the following? A separate (*CoreAPI).Resolve() func which tries its best to turn anything into a cid.Cid, and then have the actual funcs in UnixfsAPI and other following APIs accept cid.Cid and nothing else. This could be broken up into ResolveString, ResolvePath, ResolveMultihash, etc., but would always come up with either a cid.Cid, or an error.

The current specs in ipfs/interface-ipfs-core just assume multihashes everywhere, but on the other hand js-ipfs has neither a gateway nor IPNS.

[hsanjuan]

That sounds better @lgierth. I wonder if those resolve functions qualify to be part of core API or should be in other modules though (or part of cid).

I wonder if those resolve functions qualify to be part of core API or should be in other modules though (or part of cid).

We need the Core API to be able to resolve full /ipfs and /ipns paths. In the case of minimal implementations without a namesys, this means at least returning proper errors for this (e.g. ErrNoNamesys).

[whyrusleeping]

Lets make sure to keep the robustness principle in mind. I think that our 'nice' interface that we're expecting users to interact with frequently should be very easy to use.

It makes go behave like Python.

Python is quite nice to use and hack things together with, as is javascript. We should make sure to consider who this api is intended for when designing it, more advanced users can create an adder themselves and plumb things through more 'correctly'.

I'd be interested to hear @jbenet's thoughts on the matter.

[Kubuxu]

In my opinion robustness principle applies to user facing interfaces, not really dev facing interfaces, we don't want to replicate what browsers do with broken HTML.

In my opinion robustness principle applies to user facing interfaces, not really dev facing interfaces, we don't want to replicate what browsers do with broken HTML.

Eeeh the robustness principle goes down the whole stack :)

TCP implementations should follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others.

But let's stay on topic:

---

The difference between what I proposed in the #3493, and what I proposed with Resolve*() above, is where we place the being-liberal-in-what-we-accept. The former is implicit, the latter is explicit.

We have a similar separation of concerns on the HTTP API and CLI: there's all the functions that do stuff and expect direct ipfs paths (direct as in: just multihash, no links), and there's resolve, which always comes up with either a direct ipfs path , or with an error or a timeout. For user convenience there, we imply resolve in all other functions too, so that e.g. ipfs cat /ipns/ipfs.io/theme/image/logo.png works.

So on the HTTP API and CLI we're being implicit.

We should make sure to consider who this api is intended for when designing it, more advanced users can create an adder themselves and plumb things through more 'correctly'.

Yep! We should still make it super easy though to plumb things.

I feel like the explicit version is okay and easy enough, and I'm seeing another advantage: having all functions accept CIDs-only tells something to users of the Core API: "CIDs are the thing!!!"

---

I'd be interested to hear @jbenet's thoughts on the matter.

Me too! I feel like we've had a similar discussion a long while ago.

We should make sure to consider who this api is intended for when designing it

The users of the Core API want to:

• Plumb something together quickly, i.e. what go-ipfs-api (aka ipfs-shell) is provides. Super simple interfaces with not a lot of surface.
• Build proper applications embedding go-ipfs or parts of it

The first point is why it's critical to accept as many kinds of paths/CIDs/multihashes/URIs as reasonably possible. The consumer might be getting these values from ctulhu-knows-where.

Anyhow, I think it's cool to be explicit, and have Resolve() be the liberal component.

[jbenet]

I will respond with more in a bit, but quick thoughts (since others are thinking about it now):

• i'm not convinced cid.CID should be the type the core IPFS functions operate on. It should be our path.Path (really ipfs.path.Path if it was more qualified). Think about it like a file system.
• My instinct here is that we should not be asking people to resolve to CID because what we're operating on is not hashes/content-addresses, but rather the identifier of an object in the graph (a path to it). CIDs happen to be a path because /<cid> makes sense in IPFS and we're saving people the extra cognitive load of (/ip{fs,ld}/<cid>).
• Forcing to a CID in the core implies that ALL functions will behave exactly the same no matter what path to an object is used. I'm not certain that ALL functions should behave exactly the same if two paths to the exact same object are tried. There may be cases where the access path implies something.
• The robustness principle i think is a great thing to follow in general, all over the stack. (and yes, it comes from TCP.
• I would be in favor of moving the "liberality" of the main thing we take into a function (like core.Resolve as @lgierth suggests, or some other function like ParseAndResolveToCID). But what should this function output? im not sure that a cid.CID is the right thing, as described above. It may have to output a path, at which point we may be back to calling Resolve internally.

---

an interesting example:

> ipfs pin add foo
added Qme4u9HfFqYUhH4i34ZFBKi1ZsW7z4MYHtLxScQGndhgKE foo/bar/baz/abc
added QmR4waSammpkmN3xe9Vx34SRSa8L396ZFqrF2aTjXwsZUr foo/bar/baz/def
added QmYud4MjiKLmmZtzPbCBhKS9cRRnmSH6eEyEfaGCxVceBe foo/bar/baz
added QmSTGbf64dkWLDXRPcdoFyKVwbDeE2WRpE3nGFvGd1hg5Z foo/bar
added QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy foo

> ipfs cat /ipfs/QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy/bar/baz/abc
abc

> ipfs pin add -r /ipfs/QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy/bar
pinned QmSTGbf64dkWLDXRPcdoFyKVwbDeE2WRpE3nGFvGd1hg5Z recursively

Today, this means the following:

> ipfs repo gc
# QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy should be gone

> ipfs cat /ipfs/QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy/bar/baz/abc
error: QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy not found

A different semantic of the statement:

ipfs pin add -r /ipfs/QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy/bar

would pin QmSTGbf64dkWLDXRPcdoFyKVwbDeE2WRpE3nGFvGd1hg5Z recursively, and pin QmPWCKsKi66kea1GenAygQuGTPf7ANB6Rio6TLLg69UVwy directly "as a dependency".

(this may or may not be better)

I say all this because im not 100% sure that all functions should be ok just taking CIDs. i think Paths is more accurate.