This specification describes how HTTP Gateway semantics and APIs can be used over libp2p transports, and how libp2p can coexist with other HTTP services on the same host.
The libp2p+HTTP specification describes how to use libp2p with HTTP semantics over stream transports, as well as how to do discovery of what protocols are available (and where they are mounted).
.well-known/libp2p/protocolsAny libp2p application sub-protocols exposed behind /http/1.1 protocol can be
discovered by the well-known resource ([rfc8615]) at .well-known/libp2p/protocols.
In order for a pure HTTP Gateway protocol like the [trustless-gateway] to
coexist with libp2p in this environment it requires a protocol identifier to act as a key in
the .well-known/libp2p/protocols mapping file.
The /http/1.1 sub-protocol identifier for the IPFS Gateway when used over libp2p is:
/ipfs/gateway
A reference .well-known/libp2p/protocols JSON body with mapping that assumes the gateway to be mounted at /:
{
"protocols": {
"/ipfs/gateway": {"path": "/"},
}
}
Peer ID Authentication over HTTP is optional and SHOULD NOT be required by Trustless Gateway HTTP endpoint defined for /ipfs/gateway handler.
Clients following the Trustless Gateway specification MUST verify each CID individually, without being concerned with peer identity. PeerID authentication is not required for trustless retrieval and HTTP-only clients SHOULD work without it.
The /ipfs/gateway protocol identifier is shared among all Gateway specifications.
An HTTP server mounted behind the /ipfs/gateway identifier MUST expose the most basic block (application/vnd.ipld.raw)
responses from [trustless-gateway], but MAY also support other gateway types and features.
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.
We gratefully acknowledge the following individuals for their valuable contributions, ranging from minor suggestions to major insights, which have shaped and improved this specification.
