HTTP Gateway | IPFS Docs (original) (raw)

# HTTP Gateway reference

Gateways provide implementation and runtime agnostic HTTP interface for retrieving content-addressed data from IPFS with regular HTTP clients and libraries.

# API

# `GET /ipfs/{cid}[/{path}][?{params}]`

cid is a CID, the root identifier of the requested content path
path – optional path under the root CID

Optional query parameters:

filename sets the name returned in Content-Disposition HTTP header
download set to true will skip rendering and force browsers to present a 'Save as' dialog
format URL-friendly alternative to sending Accept header

# Trusted vs trustless

Gateways can be used in a trusted or trustless way. HTTP clients are in control; they decide how much trust and work is delegated to the gateway.

# Delegating trust

By default, a gateway will take care of UnixFS deserialization and return reassembled files to the client, as if they were stored in a traditional HTTP server. This means all validation happens on the gateway, and clients trust that the gateway is correctly validating content-addressed data before returning it to them.

# Example: fetching an UnixFS file from a local gateway

# Trustless, verifiable retrieval

Clients capable of verifying content-addressed data on their own, should use application/vnd.ipld.raw (opens new window) and application/vnd.ipld.car (opens new window) response types (raw blocks and CARs) and always ask for CIDs directly (/ipfs/{cid}).

This mode of operation removes the need for trusting gateway returns correct data. Client can always verify that returned bytes match the requested CID.

# Example: fetching an entire DAG as a CAR stream from a public gateway

To request application/vnd.ipld.car (opens new window) response type:

Verify CAR without running full IPFS node

CAR verification does not require running IPFS node. Clients can leverage standalone tools and libraries such as ipfs-car (opens new window):

# Example: fetching a single raw block from a public gateway

To request application/vnd.ipld.raw (opens new window) response type:

# Specifications

The HTTP Gateway specification for IPFS implementers is available at specs.ipfs.tech (opens new window). Below are links for the most useful specifications.

# HTTP

These are "low level" gateways that expose IPFS resources over HTTP protocol.

Path Gateway (opens new window) ← START HERE, other types of gateway are specified as a delta against this specification.
Trustless Gateway (opens new window) is a subset that returns verifiable response types (raw blocks and CARs)

# Web

Special types of gateway which leverage Host header in addition to URL pathname. Designed for website hosting and improved interoperability with web browsers and origin-based security model (opens new window).