API review

[vmx]

@mikeal and I want to review the current API and see how they can be made more ergonomic.

The goal is to have a nice to use and easy to implement API which aligns well with the current vision of IPLD. Breaking the API is possible and even very likely.

Currently also the spec and the format implementations are not in sync at the moment (see the open issues for more information).

Parts of it is that it will use async/await, hence aligns well with the Awesome Endeavour: Async Iterators.

We can use this issue for further discussion/referencing things.

/cc @hacdias

[richardschneider]

Where is the current spec for IPLD?

[vmx]

@richardschneider Most recent one is at ipld/specs#72

[richardschneider]

Before reviewing the API, I would like to see the IPLD use case(s) or a list of requirements. Are they available somewhere?

[mikeal]

Can we scope this to interface-ipld-format rather than "IPLD?"

The use cases for IPLD are too numerous, we're effectively talking about building data-structures to support every application vertical. The case for interface-ipld-format is more limited.

The main purpose of the interface is to provide a codec agnostic way to interact with Blocks. The primary consumer is IPFS. It needs to be able to:

• serialize
• de-serialize
• traverse paths
• list all paths (IPFS needs this, I don't think it has another use case)

Limiting the scope of the interface is that it operates on a single block at a time. For path traversals, it only resolves the path available in a single block, returning enough information for the consumer to continue traversing the path through subsequent blocks.

The interface is defined so that codecs can match the API and be plugged in to anything that consumes IPLD codecs.

Note that, based on ipld/specs#72, this interface is meant to support any IPLD codec, including those that do not support the IPLD Data Model (git, eth, etc).

[vmx]

The current review is done. Some of the discussions of a next generation API happen over here https://github.com/ipld/js-ipld-stack.