@mikeal @olizilla @autonome @warpfork @aschmahmann – this is a quick memo with my initial synthesis of the ?format= idea. Bit thin on details, but want to get early feedback/temperature check before I start elaborating on this in gateway specs in the following weeks.

This is a meta issue for streamlining various feature requests and needs under a single opt-in query parameter that enables gateway users to fetch a specific representation of a specific content path.

Support for each format can be discussed/added via a separate issue/PR – this issue is just for tracking the bigger picture around unified format paramerer.

Note: if you need CARs from an ipfs gateway today, POST to /v0/api/dag/export?arg=<cid>, see: https://docs.ipfs.io/reference/http/api/#api-v0-dag-export

MVP formats

Ability to fetch every CID as full DAG in CAR or a single Block

This is the key feature to enable Verifiable Gateway Responses and "HTTP-based transport for IPFS" (mobile browsers, IoT) without introducing even more dependency on /api/v0, and giving us flexibility for adding new features in the future.

• ?format=car – implemented in feat(gateway): Block and CAR response formats #8758
  • Returns binary stream with CAR archive for entire DAG behind the content path
  • Supersedes /api/v0/dag/export, but with better UX:
    • works on DNSLink websites that do not expose /api/v0
    • content-disposition defaults to {filename|cid}.car
• ?format=block ?format=raw – implemented in feat(gateway): Block and CAR response formats #8758
  • Returns binary array with the root block identified by CID
  • Supersedes /api/v0/block/get, but with better UX:
    • works on DNSLink websites that do not expose /api/v0
    • content-disposition defaults to {cid}.bin

CBOR / JSON

Moved to #8823

Future ideas / lower priorities

• ?format=tar|zip
  • add tarfile/zipfile downloads to HTTP gateway #7746
  • incorrect content-type for tarfile from /api/v0/get #7959
• ?format=share-img
  • Gateway: dynamic image for social sharing #8811
• ?format=unixfs-stats
  • similar to share-img but in dag-json format, could provide information about Size and Type (dir/file) and be leveraged for efficient pagination of huge directories (Gateway directory listings should be paginated #8455, Get some info about UnixFS objects on public IPFS HTTP API #8528)

Behaviors

• ?format missing
  • if codec is dag-pb or raw return file/directory
    (current gateway behavior)
  • else (codec without default behavior), return error suggesting passing ?format=car|block|..