From 21ccd422917b6f788b42d062c63fe3db63ba0580 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 27 Sep 2024 19:37:33 +0200 Subject: [PATCH 1/3] 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 --- docs/concepts/ipni.md | 70 ++++++++++++++++++++++++++++++- docs/concepts/public-utilities.md | 2 +- 2 files changed, 69 insertions(+), 3 deletions(-) diff --git a/docs/concepts/ipni.md b/docs/concepts/ipni.md index 3939cfdc2..f735c905d 100644 --- 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 index 569490f24..d3c6cb5cd 100644 --- 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 From 616564ce0ed28ec148d250c018e5656a6bf79912 Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Mon, 30 Sep 2024 12:16:33 +0200 Subject: [PATCH 2/3] Update docs/concepts/ipni.md --- docs/concepts/ipni.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/ipni.md b/docs/concepts/ipni.md index f735c905d..bfda5fabc 100644 --- a/docs/concepts/ipni.md +++ b/docs/concepts/ipni.md @@ -118,7 +118,7 @@ Endpoint produces human-readable JSON objects: 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. +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 From 60575a3f5596a8223016c524db8a5cfcfd9fd520 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 2 Oct 2024 16:40:36 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com> Co-authored-by: Andrew Gillis <11790789+gammazero@users.noreply.github.com> --- docs/concepts/ipni.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/concepts/ipni.md b/docs/concepts/ipni.md index bfda5fabc..0572f3cca 100644 --- a/docs/concepts/ipni.md +++ b/docs/concepts/ipni.md @@ -67,7 +67,7 @@ By providing this additional layer of information, the indexer helps to speed up ### 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/). +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 @@ -115,7 +115,7 @@ Endpoint produces human-readable JSON objects: } ``` -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. +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. @@ -131,7 +131,7 @@ Light IPFS clients may prefer to query [delegated-ipfs.dev/routing/v1](https://d ### 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. +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.