fix: add /routing/v1 example to ipni.md (#1931)

Co-authored-by: Daniel Norman <[email protected]> Co-authored-by: Andrew Gillis <[email protected]>
ipfs · Oct 2, 2024 · 27e0757 · 27e0757
1 parent 9213d4c
commit 27e0757
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 the 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 client code reuse across all compatible routing systems.
+
+:::callout TIP
+To start receiving results immediately, 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
+
+The IPNI also provides its 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