fix: add /routing/v1 example ipni.md

kubo, rainbow and helia all use /routing/v1, yet the document has a prominent example that hits /cid this lead to more than one outage where only /cid was checked, but /routing/v1 did not work correctly this adds a prominent example how /routing/v1 is used and whi, links to relevant specs, and adds some useful references, as a bare minimum to adjust perspective how IPFS uses IPNI
ipfs · Sep 27, 2024 · 21ccd42 · 21ccd42
1 parent 9213d4c
commit 21ccd42
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 3 deletions.
diff --git a/docs/concepts/ipni.md b/docs/concepts/ipni.md
@@ -65,7 +65,73 @@ When a user searches for a piece of data using a CID or multihash, the indexer i
 
 By providing this additional layer of information, the indexer helps to speed up data location and retrieval, reduce resource consumption, and improve the overall scalability of IPFS.
 
-## Example application
+### Example: finding providers via `/routing/v1`
+
+Most of the time, IPFS implementations interact with IPNI by querying the HTTP endpoint compatible with [Delegated Routing V1 API Specification](https://specs.ipfs.tech/routing/http-routing-v1/).
+
+```plaintext
+$ curl https://cid.contact/routing/v1/providers/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
+```
+
+Endpoint produces human-readable JSON objects:
+
+```json
+{
+  "Providers": [
+    {
+      "Addrs": [
+        "/dns4/bitswap.filebase.io/tcp/443/wss"
+      ],
+      "ID": "12D3KooWGtYkBAaqJMJEmywMxaCiNP7LCEFUAFiLEBASe232c2VH",
+      "Protocols": [
+        "transport-bitswap"
+      ],
+      "Schema": "peer",
+      "transport-bitswap": "gBI="
+    },
+    {
+      "Addrs": [
+        "/ip4/212.6.53.27/tcp/80/http"
+      ],
+      "ID": "12D3KooWHEzPJNmo4shWendFFrxDNttYf8DW4eLC7M2JzuXHC1hE",
+      "Protocols": [
+        "transport-ipfs-gateway-http"
+      ],
+      "Schema": "peer",
+      "transport-ipfs-gateway-http": "oBIA"
+    },
+    {
+      "Addrs": [
+        "/ip4/72.52.65.166/tcp/26101"
+      ],
+      "ID": "12D3KooWHKChM2uYi4EXREaCGtaxersCsp7hbFiMqMUK8o7CgV6Q",
+      "Protocols": [
+        "transport-graphsync-filecoinv1"
+      ],
+      "Schema": "peer",
+      "transport-graphsync-filecoinv1": "kBKjaFBpZWNlQ0lE2CpYKAABgeIDkiAg1l4zEzA4zeGlv3N7u4iMbysxTBMRUrquyMVzQejTeh9sVmVyaWZpZWREZWFs9W1GYXN0UmV0cmlldmFs9Q=="
+    }
+  ]
+}
+```
+
+Each result follows [PeerSchema](https://specs.ipfs.tech/routing/http-routing-v1/#peer-schema), and is the same format as every other delegated routing endpoint in the IPFS ecosystem. This allows clients to write code once and use across all routing systems.
+
+:::callout TIP
+To start receiving results immediatelly, enable [streaming responses](https://specs.ipfs.tech/routing/http-routing-v1/#streaming) by passing `Accept: application/x-ndjson` HTTP Header.
+
+```plaintext
+$ curl -H 'Accept: application/x-ndjson' https://cid.contact/routing/v1/providers/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
+```
+:::
+
+:::callout FYI
+Light IPFS clients may prefer to query [delegated-ipfs.dev/routing/v1](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing) endpoint, which is a [`someguy` caching proxy](https://github.com/ipfs/someguy#readme) for both Amino DHT and IPNI at `cid.contact`.
+:::
+
+### Example: finding providers via IPNI-specific `/cid` endpoint
+
+IPNI also provides own HTTP API(s) which may be preferable when IPNI-specific information is desired.
 
 To demonstrate the practical application and usage of IPNI, this section will walk through a hands-on example involving the `cid.contact` indexer tool. The `cid.contact` tool leverages IPNI to return provider record information for a given CID.
 
@@ -213,7 +279,7 @@ To demonstrate the practical application and usage of IPNI, this section will wa
     }
     ```
 
-### Response explained
+#### Response explained
 
 This response returns multiple provider records, which indicates that the data identified by this CID was found at multiple providers. For example, the first provider is specified by the following record:
 

diff --git a/docs/concepts/public-utilities.md b/docs/concepts/public-utilities.md
@@ -55,7 +55,7 @@ The underlying IPFS nodes backing the gateways support retrieving data from peer
    - TCP or WS or WSS, Yamux, TLS or Noise
    - WebTransport
 - Support the [Bitswap](./bitswap.md) protocol ([v1.2](https://specs.ipfs.tech/bitswap-protocol/#bitswap-1-2-0), [v1.1](https://specs.ipfs.tech/bitswap-protocol/#bitswap-1-1-0) or [v1.0](https://specs.ipfs.tech/bitswap-protocol/#bitswap-1-0-0))
-- Have either advertised their data to the Amino DHT, or have advertised to IPNI such that their data has been indexed by [cid.contact](https://cid.contact)
+- Have either advertised their data to the [Amino DHT](./glossary.md#amino), or have advertised to [IPNI](./glossary.md#ipni) such that their data has been indexed by [cid.contact](https://cid.contact)
 
 ## Other Public Gateways