Delegated IPNS HTTP API

Summary

This IPIP specifies /routing/v1/ipns HTTP API to offload naming system onto another process or server.

Motivation

One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative systems.

Expanding on the motivations of :cite[ipip-0337], the work here concentrates on delegation of IPNS over HTTP API. Naming is part of the core IPFS DHT functionality. The performance of naming system over the IPFS DHT can suffer from long delays due to churn of records and quorum requirements.

Detailed design

Add /routing/v1/ipns to the existing :cite[http-routing-v1] specification.

Design rationale

The rationale for delegated IPNS over HTTP APIs closely follows the reasoning listed in :cite[ipip-0337].

The document proposes the following:

• HTTP GET and PUT semantics for publication and resolution of IPNS records.
• Use of existing :ref[IPNS Record] serialization format as HTTP Content-Type application/vnd.ipfs.ipns-record.

User benefit

The ability to offload naming to another process or server using a simple HTTP API brings several benefits:

• It reduces the resource drain on light clients such as JavaScript running on a web page, mobile devices, IoT devices, and gateway HTTP services.
• It enables scaling of IPNS resolution separately from retrieval and deserialization/verification services.
• Expands the utility of IPNS beyond IPFS nodes, contributes to its broader adoption and impact by reducing integration costs.

Compatibility

See the "Compatibility" section of :cite[ipip-0337].

Serialization Format

Standard IPNS record serialization format is used, making it fully compatible with the existing IPNS ecosystem.

:cite[ipns-record] uses application/vnd.ipfs.ipns-record protobuf serialization format. This format is widely in use in IPNS over PubSub and DHT routing systems. Further, interoperability across the existing and HTTP APIs is also desirable in order to reduce the barrier for adoption of the delegated HTTP APIs.

To maximize interoperability with existing ecosystem, the canonical IPNS record serialization format :cite[ipns-record] (0x0300) can be requested with content type application/vnd.ipfs.ipns-record.

Security

All interaction over the APIs should use TLS to protect against third-party observation and tampering. Additionally, the IPNS records must be validated according to the rules stated in :cite[ipns-record] before further processing.

To avoid Denial of Service attack, maximum IPNS record size defined in :cite[ipns-record] applies.

Privacy in delegated IPNS is out of scope for this IPIP.

Alternatives

See:

• IPNS over (libp2p over HTTP). While it may be possible in the future, it has more narrow utility and way bigger implementation complexity than libp2p-agnostic HTTP API with protobuf GET/PUT.
• Reframe; it was deprecated and now removed. Historical reasons can be found in :cite[ipip-0337].
• JSON IPNS Record representation was descoped due to open question how signing should work and unclear use case (discussion).
• API-specific max record size was descoped, as it would introduce interop problems harmful to the IPNS ecosystem.

Copyright

Copyright and related rights waived via CC0.