[FEATURE] - Documentation and Integration Clarification

[nhenin]

Internal/External : Internal

Context

The current repository lacks documentation, making it unclear what direction Intersect is taking with it.

When the repository is updated, projects that depend on it face difficulties upgrading due to the following reasons, among others:

• cardano-node bypasses the dependencies cardano-api is supposed to abstract.
• Similar concepts but from different core domains are mixed : e.g : Ledger.Coin and Cardano.API.Lovelace (that has been removed in 8.40 and not explained in the changelog > see #607 )

Here is the current documentation of the Readme :

I am requesting the addition of comprehensive documentation to assist projects relying on this dependency in progressing with their own development.

What is the "vision" of this repository?

The repository mentions the integration of the ledger, consensus, and networking repositories.

Is cardano-api intended to be the interface for handling Cardano-related tasks? If so, why do some projects use cardano-api but also directly access the repositories behind the API?

I was expecting to see something more cohesive, like this:

But I can see that most of the repositories using this API are bypassing it :

Cardano Node and Cardano Submit API

Cardano CLI

These issues impact projects built on top of these libraries. I believe it starts with a clarification on the project vision. What is cardano-api aimed to be ?

Documentation Improvement Proposal

Repository Vision Detailed

The README should clearly outline the vision of the repository, including its purpose and long-term goals. This section should also clarify the intended role of cardano-api in handling Cardano-related tasks, addressing why some projects might use both cardano-api and the underlying repositories directly.

The current cardano-node documentation links should be removed , it is irrelevant here.

High-Level Features and Examples of Code

The README should include:

• A detailed description of the features the repository aims to provide.
• Code examples demonstrating how to use these features.
• Information on where this repository is used (e.g., cardano-node, cardano-cli, cardano-submit-api).

High-Level Issues and Roadmap/Backlog

Please provide details on:

• The current focus and ongoing work of the core maintainers.
• The roadmap and backlog for future development.

Adding comprehensive documentation will help projects relying on this dependency better understand its capabilities and future direction, facilitating smoother development and integration.

[nhenin]

Hi, any feedback ?

[Jimbo4350]

:wave: Thanks for raising this issue:

Is cardano-api intended to be the interface for handling Cardano-related tasks? If so, why do some projects use cardano-api but also directly access the repositories behind the API?

The ledger, consensus and networking apis were challenging to consume in the past which is why cardano-api was created. We have wrappers around types exposed from these libraries with the intention of making it easier to consume. Recently the ledger's api has dramatically improved and therefore we will be relying more on ledger's api instead of unnecessarily wrapping things. I.e https://github.com/IntersectMBO/cardano-api/commit/46c1e605244fb3d01deda3451a0b56763c7c9370. This helps us two fold: It reduces the maintenance burden on my team and it makes it easier to track down bugs in our implementation.

why do some projects use cardano-api but also directly access the repositories behind the API?

Short cuts. Rather than taking the time to expose a type or function you need to work with via cardano-api, it's easier to import the module needed directly. This is something we are addressing this year.

I don't disagree with the issues you have raised. Hang tight we will be addressing this in the near future.