Ceramic Javascript API about cips HOT 17 CLOSED

Thanks @simonovic86! Looks great.
@michaelsena is the next step to just create a PR for this?

from cips.

Makes sense. I think it's enough, too 👍

from cips.

Makes sense. Let's keep the new method in the Ceramic API.

I totally agree for the InitOpts. We will definitely change it a bunch of times. That said, we don't need to define it now :)

from cips.

@simonovic86 @oed this is great! Quick question, if we wanted to separate out a commit function as discussed the other day, would we need a new CIP to define that, which would be submitted separately? If so, then let's create a PR - this looks good to go.

from cips.

Looks great. One question.

Should we define the version field or similar and expose it in the APIs interface? If we introduce some feature in the future which can possibly break the backward compatibility we should be able to detect API versions.

from cips.

@simonovic86 Hm, what version would be returned from this? The version of the api itself? My concern with this is that it might be confusing since the ceramic-core version will likely differ from the ceramic-http-client version.
Or would the version field simply say something like [email protected] or [email protected]?

from cips.

@oed I thought about the API version therefore I think its ceramic-http-client.

I think it's ok for ceramic-core version to differ from the ceramic-http-client version. I guess that API versions will progress slower than the core. Does that make sense?

from cips.

I'm not sure. They might change either way. Isn't it enough that the packages have versions though? It would be weird if ceramic-core exposes the version of the http client right?

from cips.

@simonovic86 would be good to circle back and rewrite this Draft after you've dug through the code :)

from cips.

@michaelsena definitely! I'll post a detailed feedback after I run more tests :)

from cips.

These are the changes based on the first draft-0 implementation of the proposed API. Let's reiterate more through it.

The Doctype interface should include the document ID since we are depending on it in the API. With that said, the minimal Doctype interface should look like this:

interface Doctype {
    id: string;
    doctype: string;
    content: object;
    owners: Array<string>;
    state: DocState;
    head: CID;
}

There are situations where we need to sign the genesis record on document creation before applying it (TileHandler, etc.). We should leave that to the Doctype side and not to the DoctypeHandler since it is more natural for the client to sign it and not the Ceramic instance. With that said the minimal DoctypeHandler interface should look something like this:

interface DoctypeHandler<T extends Doctype> {
    name: string; // the string name of the doctype

    applyRecord(record: any, cid: CID, context: Context, state?: DocState): Promise<DocState>;
}

The Ceramic pinning API mimics the IPFS pinning API. We could change the ls return type to Promise<AsyncIterable<string>>. The interface could look like this:

interface PinApi {
 
    add(docId: string): Promise<void>;

    rm(docId: string): Promise<void>;

    ls(docId?: string): Promise<AsyncIterable<string>>;
}

Since create/update/sign/etc. happens in the Doctype abstraction/layer these are the proposed changes to the CeramicAPI interface:

interface CeramicApi {
    pin: PinApi;
    ipfs: Ipfs.Ipfs;

    addDoctype<T extends Doctype>(doctypeHandler: DoctypeHandler<T>): void;

    createFromGenesis<T extends Doctype>(record: any, opts?: InitOpts): Promise<T>;

    load<T extends Doctype>(docId: string, opts: InitOpts): Promise<T>;

    applyRecord<T extends Doctype>(docId: string, record: object): Promise<T>;

    close(): Promise<void>; // gracefully close the ceramic instance
}

The createFromGenesis enables us to have different layers of abstraction between Doctype and DoctypeHandler.

Doctype implements functionality for manipulating the document and the DoctypeHandler applies those changes.

We should also describe the InitOpts interface. Maybe that interface could be more flexible.

Let's discuss more about the APIs and naming as well! :)

from cips.

Thanks @simonovic86 that all makes sense.
About CeramicApi: I still think we need the new method (maybe called something else). If we don't have that there is no good way to construct new documents without having to create the genesis-record.

I assume InitOpts will likely change quite often adding new options so I didn't bother defining it.

from cips.

Updated this according to our discussions and your implementation @simonovic86 👍

from cips.

Updated this according to our discussions and to current implementation.

from cips.

We should also add the PR that contains the changes to this CIP in the implementations section.

from cips.

@simonovic86 @oed this is great! Quick question, if we wanted to separate out a commit function as discussed the other day, would we need a new CIP to define that, which would be submitted separately? If so, then let's create a PR - this looks good to go.

I think not. We can elaborate more about the topic but I think that we are covered with these APIs.

from cips.

Outdated, closing.
Please refer to the ceramic documentation: https://ceramicnetwork.github.io/js-ceramic/api/

from cips.