docs: reference/http/gateway/#api

Replaces placeholder with basic information about the API
and points at follow-up resources (how-tos, specs)

docs/how-to/address-ipfs-on-web.md

@@ -55,7 +55,7 @@ For example, a website can load static assets from content-addressed paths:
 User agents that support IPFS, such as a browser with [ipfs-companion](https://docs.ipfs.io/install/ipfs-companion/), may recognize the `/ipfs/<CID>` content path and load the related asset over IPFS instead of HTTP. User agents without IPFS support still get the correct data from the original HTTP server.
 :::
 
-### Path gateway
+## Path gateway
 
 In the most basic scheme, a URL path used for content addressing is effectively a resource name without a canonical location. The HTTP server provides the location part, which makes it possible for browsers to interpret an IPFS content path as relative to the current server and just work without a need for any conversion:
 
@@ -78,7 +78,7 @@ https://ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.ht
 https://ipfs.io/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html
 ```
 
-### Subdomain gateway
+## Subdomain gateway
 
 When [origin-based security](https://en.wikipedia.org/wiki/Same-origin_policy) is needed, [CIDv1](../concepts/content-addressing.md#identifier-formats) in case-insensitive encoding such as Base32 or Base36 should be used in the subdomain:
 
@@ -157,7 +157,7 @@ $ ipfs cid format -v 1 -b base36 --codec libp2p-key QmNnooDu7bfjPFoTZYxMNLWUQJyr
 k2k4r8jl0yz8qjgqbmc2cdu5hkqek5rj6flgnlkyywynci20j0iuyfuj
 ```
 
-### DNSLink gateway
+## DNSLink gateway
 
 The gateway provided by the IPFS daemon understands the `Host` header present in HTTP requests and will check if [DNSLink](../concepts/dnslink.md) exists for a specified [domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name).
 If DNSLink is present, the gateway will return content from a path resolved via DNS TXT record.

docs/reference/http/gateway.md

@@ -5,34 +5,112 @@ description: HTTP Gateway API reference for IPFS clients.
 
 # HTTP Gateway reference
 
-Gateways provide implementation and runtime agnostic HTTP interface for retrieving [content-addressed](/concepts/glossary/#content-addressing) data from IPFS with regular HTTP clients and libraries.
+Gateways provide implementation and runtime agnostic HTTP interface for retrieving [content-addressed](../../concepts/glossary/#content-addressing) data from IPFS with regular HTTP clients and libraries.
 
-::: tip Before you dive into low level specifications...
 
-Make sure you understand [how to address IPFS on the web](../how-to/address-ipfs-on-web/), and what are differences between [Path](/how-to/address-ipfs-on-web/#path-gateway) and [Subdomain Gateways](/how-to/address-ipfs-on-web/#subdomain-gateway).
+## API
+
+### `GET /ipfs/{cid}[/{path}][?{params}]`
+
+- `cid` is a [CID](https://docs.ipfs.io/concepts/glossary/#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](../../how-to/address-ipfs-on-web/), and what are differences between [Path](../../how-to/address-ipfs-on-web/#path-gateway) and [Subdomain Gateways](../how-to/address-ipfs-on-web/#subdomain-gateway).
+
+:::
+
+## Trusted vs trustless
+
+Gateways can be used in a trusted or trustless way.
+HTTP clients are in control, 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 the gateway is correctly validating content-addressed data before returning it to them.
+
+#### Example: fetching an UnixFS file
+
+```bash
+$ curl -L "https://ipfs.io/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](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) and [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) response types (raw [blocks](../concepts/glossary/#block) and [CARs](../concepts/glossary/#car)), and always ask for CIDs directly (`/ipfs/{cid}`).
+
+#### Example: fetching a raw block
+
+Using `Accept` HTTP header with [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) type:
+
+```bash
+$ curl -L -H "Accept: application/vnd.ipld.raw" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" > raw-block.bin
+$ ipfs block put raw-block.bin
+bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
+```
+
+
+::: tip
+
+An alternative is to pass `?format=raw` URL parameter:
+
+<https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw>
+
 :::
 
-::: warning SPECIFICATION (WORK IN PROGRESS)
+#### Example: fetching an entire DAG as a CAR stream
+
+Using `Accept` HTTP header with [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) type:
+
+```bash
+$ curl -H "Accept: application/vnd.ipld.car" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" > dag.car
+$ ipfs dag import dag.car
+```
+
+::: tip
+
+An alternative is to pass `?format=car` URL parameter:
+
+<https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=car>
+
+:::
+
+## Specifications
+
+HTTP Gateway specification for IPFS implementers is available in [ipfs/specs](https://github.com/ipfs/specs/blob/main/http-gateways/#readme) repository.
+Below are links for the most useful specifications.
 
-<!-- TODO update this section (at least the links) when ipfs/specs PR lands -->
-HTTP Gateway specification for IPFS implementers is available in [ipfs/specs](https://github.com/ipfs/specs/blob/main/http-gateways/#readme):
 
 ### HTTP
 
 These are "low level" gateways that expose IPFS resources over HTTP protocol.
 
-* [PATH_GATEWAY.md](https://github.com/ipfs/specs/blob/main/http-gateways/PATH_GATEWAY.md) ← **START HERE**
-* [TRUSTLESS_GATEWAY.md](https://github.com/ipfs/specs/blob/main/http-gateways/TRUSTLESS_GATEWAY.md)
+* [Path Gateway](https://github.com/ipfs/specs/blob/main/http-gateways/PATH_GATEWAY.md) ← **START HERE**, other types of gateway are specified as a delta against this specification.
+* [Trustless Gateway](https://github.com/ipfs/specs/blob/main/http-gateways/TRUSTLESS_GATEWAY.md) is a subset that returns verifiable response types (raw [blocks](../concepts/glossary/#block) and [CARs](../concepts/glossary/#car))
 
 ### 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](https://en.wikipedia.org/wiki/Same-origin_policy).
 
-* [SUBDOMAIN_GATEWAY.md](https://github.com/ipfs/specs/blob/main/http-gateways/SUBDOMAIN_GATEWAY.md)
-* [DNSLINK_GATEWAY.md](https://github.com/ipfs/specs/blob/main/http-gateways/DNSLINK_GATEWAY.md)
+* [Subdomain Gateway](https://github.com/ipfs/specs/blob/main/http-gateways/SUBDOMAIN_GATEWAY.md)
+* [DNSLink Website Hosting](https://github.com/ipfs/specs/blob/main/http-gateways/DNSLINK_GATEWAY.md)
+
+::: tip
 
-If you are a gateway operator or an implementer, consider providing feedback in [ipfs/specs](https://github.com/ipfs/specs/) repository.
+If you are a gateway operator or an implementer, consider joining [Gateway Operators Forum](https://discuss.ipfs.io/c/31)
 
 :::
 
-<!-- TODO document endpoints in brief and link to ipfs/specs for more details -->

package.json

@@ -9,12 +9,12 @@
     "@vuepress/plugin-active-header-links": "^1.9.7",
     "@vuepress/plugin-back-to-top": "^1.9.7",
     "@vuepress/plugin-google-analytics": "^1.9.7",
-    "@vuepress/plugin-html-redirect": "^0.1.2",
+    "@vuepress/plugin-html-redirect": "^0.1.4",
     "@vuepress/plugin-last-updated": "^1.9.7",
     "husky": "^8.0.1",
     "lint-staged": "^13.0.3",
     "markdown-it-deflist": "^2.1.0",
-    "markdown-it-footnote": "^3.0.2",
+    "markdown-it-footnote": "^3.0.3",
     "markdown-it-image-lazy-loading": "^1.2.0",
     "markdown-it-imsize": "^2.0.1",
     "markdown-it-task-lists": "^2.1.1",