Reserve "/api/v0/extensions/{uuid}/" or similar for api calls to non-standard enhancements of go-ipfs

[bombus-lapidarius]

Checklist

• My issue is specific & actionable.
• I am not suggesting a protocol enhancement.
• I have searched on the issue tracker for my issue.

Description

Reserve "/api/v0/extensions/{uuid}/" or similar for api calls to non-standard functionality enhancements of go-ipfs, e.g. transparent encryption or the CID allow / deny API proposal in #7871.

This proposal is inspired by the well thought out approach to extensibility and modularity of the RISC-V microprocessor instruction set architecture, as outlined in the RISC-V microprocessor ISA specification (pages 141-152). It refers to the "front facing" api, not to any actual IPFS protocols themselves.

In short, the idea is to distinguish between

• mandatory core functionality a user of the api can always expect from an IPFS implementation confirming to a specific minimum version of IPFS,
• standard extensions, which are common but not universally present and where api calls can be directed at well known api endpoints, and
• non-standard extensions, where the creators of those extensions are responsible for back- and forwards compatibility of their api (which would have all its endpoints isolated under its custom namespace / UUID).

This way the functionality of go-ipfs could be enhanced by using a modified version of go-ipfs itself, or by hiding an unmodified go-ipfs node behind a proxy that provides the additional functionality (e.g. transparent encryption) without the risk of running into collisions with standard api endpoints in the future.

In the example with the transparent encryption layer the proxy could perform decryption and encryption operations on data it gets from or puts into ipfs, while any "out-of-band" actions or configuration relating to this additional functionality would be accessed via calls to its unique api endpoints under "/api/v0/extensions/" .

Obviously, it also eliminates the need for creators of non-standard extensions to coordinate with each other when naming api endpoints. At the same time, changes to any part of the api except under "/api/v0/extensions/" can focus on core (or closely related) IPFS functionality.

[lidel]

@bombus-lapidarius thank you for filling this.

Quick disclaimer:

• HTTP RPC API at /api/v0 is not "IPFS API".
  • It is RPC API specific to go-ipfs daemon. It was never intended to be exposed outside of localhost, nor it is a "standard" set in stone, just a convention of go-ipfs implementation between ipfs daemon and its CLI client.
  • Error handling in many of RPC commands relies on Trailer headers, which are not supported by modern browsers.
  • A small subset of /api/v0 is exposed on gateways, but we are working towards making that unnecessary (starting with Gateway support for /ipfs/{cid}?format=car|raw|... #8234).
  • We want Gateways endpoints at /ipfs/ and /ipns/ to be the way of interacting with IPFS that is fully compatible with browsers (superseding most of the common /api/v0 tasks and being "the generic HTTP interface for interacting with IPFS")

The idea of having a convention of /api/v0/extensions/{uuid}/ for people who fork or augment go-ipfs with additional middleware is sensible, but I am closing this as there does not seem anything that needs to be implemented here – it is just a convention for internal API in go-ipfs forks, not something one would expose on public internet.

I'm taking a note of RICS spec approach – we may document similar suggestion for extension mechanism on gateways (the gateway spec is being created this year, so people can implement own IPFS nodes without the need for reimplementing /api/v0).