Skip to content

Commit

Permalink
Add support for listing cascade options
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
masih committed Jan 27, 2023
1 parent 3de1049 commit fa14d37
Showing 1 changed file with 19 additions and 6 deletions.
25 changes: 19 additions & 6 deletions IPNI.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit fa14d37

Please sign in to comment.