(RFC) Building a repository of common canister interfaces

Developers
1

I had this idea a couple of months back, and wanted to gather comments from the public.

In order to have an open internet, we need an open standard of interfaces to build around. The goal of this design is to have a repository of such interfaces.

Each interface would have a purpose and a name (and documentation). For example, we are in the process of reworking the wallet canister, and it requires a callback to an API endpoint of your canister. Therefore, we need a DID that people can use to verify that their canister is compatible with that endpoint (and its signature). Since DID signatures are also covariant, we can version those DIDs with backward compatible changes and versioning.

Since DID services are a flat namespace, I am going to suggest the following;

  1. the name of the interface must be alphanumeric, but starts with a letter and follow camelCase. e.g. assets or managementCanister
  2. every function exported by the service should have the name of the interface (as a namespace), followed by _, then by the name of the method using camelCase, e.g. wallet_createCanister.
  3. if a breaking change must happen, a new interface needs to be created. It is suggested to simply append a major version number at the end of the existing interface name (e.g. assets2).
  4. To avoid breaking changes as much as possible, the interface should follow the best practice of receiving a record with optional fields and return a single record with potentially optional fields.
  5. A repository of those DID files would be kept up to date, accept PRs and make tests (to ensure DID can build), and maybe publish documentation in some way.

What do you think?

3 Likes
3

:+1: for such a community-based approach to growing our platform!

  • To avoid breaking changes as much as possible, the interface should follow the best practice of receiving a record with optional fields and return a single record with potentially optional fields.

The return record doesn’t have to use optional fields; Candid allows you to return additional (non opt) fields without breaking existing clients.

But it is advisable to wrap all variants that you return in opt, so that you can extend the variant later (old clients will parse new variant tags as null). Maybe I’ll include such best practices in the documentation that’s slowly growing in https://github.com/dfinity/candid/pull/158 (although best practices have the risk of being contentious – not everyone thinks that the “single record argument idiom” is necessary or good :wink: )

3 Likes