Skip to content

Latest commit

 

History

History
136 lines (80 loc) · 6.21 KB

gateway.md

File metadata and controls

136 lines (80 loc) · 6.21 KB
title description
HTTP Gateway
HTTP Gateway API reference for IPFS clients.

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

::: tip Before you continue

Make sure you understand how to address IPFS on the web and the differences between Path Gateways and Subdomain Gateways.

:::

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

$ curl "http://127.0.0.1:8080/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" > cat.jpg

::: tip

When fetching a CID directly, one can include a filename parameter with file name to be used in Content-Disposition HTTP header: https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?filename=cat.jpg

:::

Trustless, verifiable retrieval

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

::: callout

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 response type:

$ curl -H "Accept: application/vnd.ipld.car" "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car" -L > dag.car
$ ipfs dag import dag.car

::: tip

A Client SHOULD include the format query parameter in the request URL, ideally in addition to the Accept header. This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.

https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car

:::

::: tip 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:

$ npm i -g ipfs-car
$ curl "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car" -L | ipfs-car
$ ls ./bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q/
1007 - Sustainable - alt.txt
1007 - Sustainable - transcript.txt
1007 - Sustainable.png

:::

Example: fetching a single raw block from a public gateway

To request application/vnd.ipld.raw response type:

$ curl -H "Accept: application/vnd.ipld.raw" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw" -L > raw-block.bin
$ ipfs block put raw-block.bin
bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

::: tip

A Client SHOULD include the format query parameter in the request URL, ideally in addition to the Accept header. This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.

https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw

:::

Specifications

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

HTTP

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

  • Path Gateway ← START HERE, other types of gateway are specified as a delta against this specification.
  • Trustless Gateway 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.

::: tip

If you are a gateway operator or an implementer, consider testing with gateway-conformance test suite.

:::