libp2p+HTTP Transport Gateway Specification

status: draft
Adin Schmahmann (Protocol Labs) GitHub
Marcin Rataj (Protocol Labs) GitHub
Commit History
GitHub ipfs/specs (pull requests, new issue, open issues)

1. Introduction

This specification describes how HTTP Gateway semantics and APIs can be used over libp2p transports.

2. Specification

The libp2p+HTTP specification describes how to use HTTP semantics over stream transports, as well as how to do discovery of what protocols are available (and where they are mounted).

2.1 .well-known/libp2p

libp2p application sub-protocols exposed behind /http/1.1 protocol can be discovered by the well-known resource ([rfc8615]) at .well-known/libp2p.

2.1.1 Protocol identifier

In order for a given HTTP Gateway protocol like the [trustless-gateway] to work in this environment it requires a protocol identifier to act as a key in the .well-known/libp2p mapping file.

The /http/1.1 sub-protocol identifier for the IPFS Gateway when used over libp2p is:


2.1.2 Protocol mounting

A reference .well-known/libp2p JSON body with mapping that assumes the gateway to be mounted at /:

  "protocols": {
    "/ipfs/gateway": {"path": "/"},

3. Gateway type detection

The protocol identifier is shared among Gateway specifications.

HTTP server mounted behind the /ipfs/gateway identifier MUST expose [trustless-gateway], but is free to also support other gateway types and features.

Signaling Features on HTTP Gateways is wip in IPIP-425.

Until the IPIP is finalized, client implementations SHOULD perform feature detection on their own, or assume only the most basic block (application/vnd.ipld.raw) response type from [trustless-gateway] is available.

A. References

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:
Well-Known Uniform Resource Identifiers (URIs). M. Nottingham. IETF. May 2019. Proposed Standard. URL:
Trustless Gateway Specification. Marcin Rataj; Henrique Dias. 2023-06-20. URL: