From fa14d372a34e5151dbb009f3b43f4733e7eb3e8d Mon Sep 17 00:00:00 2001 From: "Masih H. Derkani" Date: Fri, 27 Jan 2023 15:43:32 +0000 Subject: [PATCH] Add support for listing cascade options Specify protocol to find out what cascade options are available to a client using `OPTIONS` method and a specific HTTP response header. This enables clients to programmatically determine the alternative routing systems to which a lookup may optionally be cascaded. Add extra wording to clarify that there are no constraints on the order by which results are returned at the presence of `cascade` query option. --- IPNI.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/IPNI.md b/IPNI.md index 41bf358..adedd47 100644 --- a/IPNI.md +++ b/IPNI.md @@ -453,6 +453,22 @@ to fetch the advertisement chain. An indexer node can be queried over HTTP for a multihash or a CID. + +#### Cascading Lookup + +The HTTP query API supports cascading queries for a given multihash or CID onto alternative routing systems in addition to searching IPNI records. +A client may optionally specify a query parameter with key set to `cascade`, and value set to comma separated alternative routing systems, which are also searched for records. + +The specification imposes no constraints on the order by which the results are returned. +Implementers are free to return results as they are found. + +The alternative routing systems currently supported is: + * `ipfs-dht`: equivalent to searching records on the IPFS network. + +A client may discover the list of alternative routing systems supported by a server via sending `OPTIONS` request. +In response, the server may include `X-IPNI-Allow-Cascade` header key, with value as the comma separated list of alternative routing systems supported. +The absence of this header key implies that the server does not offer cascading lookups. + #### `GET /cid/{cid}` Given a CID as path parameter, returns a list of its content providers. The lookup ignores CID codec @@ -465,8 +481,7 @@ and uses the multihash portion of the CID only. ##### Query Parameters -* `cascade` - _Optional_. The comma separated alternative routing systems to which the lookup is cascaded in addition to searching IPNI index records. If unspecified, only IPNI index records are searched. Supported values: - * `ipfs-dht`- The IPFS Kademlia DHT. +* `cascade` - _Optional_. The comma separated alternative routing systems to which the lookup is cascaded in addition to searching IPNI index records. If unspecified, only IPNI index records are searched. See [Cascading Lookup](#cascading-lookup) ##### Response @@ -522,8 +537,7 @@ Given a multihash as path parameter, returns a list of its content providers. ##### Query Parameters -* `cascade` - _Optional_. The comma separated alternative routing systems to which the lookup is cascaded in addition to searching IPNI index records. If unspecified, only IPNI index records are searched. Supported values: - * `ipfs-dht`- The IPFS Kademlia DHT. +* `cascade` - _Optional_. The comma separated alternative routing systems to which the lookup is cascaded in addition to searching IPNI index records. If unspecified, only IPNI index records are searched. See [Cascading Lookup](#cascading-lookup) ##### Response @@ -592,8 +606,7 @@ Base58 string representation. ##### Query Parameters -* `cascade` - _Optional_. The comma separated alternative routing systems to which the lookup is cascaded in addition to searching IPNI index records. If unspecified, only IPNI index records are searched. Supported values: - * `ipfs-dht`- The IPFS Kademlia DHT. +* `cascade` - _Optional_. The comma separated alternative routing systems to which the lookup is cascaded in addition to searching IPNI index records. If unspecified, only IPNI index records are searched. See [Cascading Lookup](#cascading-lookup) ##### Response