diff --git a/IPNI.md b/IPNI.md index 0455c69..0ccebcc 100644 --- a/IPNI.md +++ b/IPNI.md @@ -459,6 +459,22 @@ to fetch the advertisement chain. An indexer node can be queried over HTTP for a multihash or a CID. This section provides a summary of the HTTP query APIs. A full OpenAPI specification of the APIs can be found [here](schemas/v1/openapi.yaml). + +#### 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 @@ -469,6 +485,10 @@ and uses the multihash portion of the CID only. * `cid` - _Required_. The default string representation of the Cid. Currently, Base32 is used for CIDv1 as the encoding for the multibase string and Base58 is used for CIDv0. +##### 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. See [Cascading Lookup](#cascading-lookup) + ##### Response * `application/json` - JSON encoded [`FindResponse`][find-response-schema]. See [JSON Find Response](#json-find-response) example. @@ -488,6 +508,11 @@ Given a multihash as path parameter, returns a list of its content providers. * `multihash` - _Required_. The Base58 string representation of multihash value. +##### 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. See [Cascading Lookup](#cascading-lookup) + + ##### Response * `application/json` - JSON encoded [`FindResponse`][find-response-schema]. See [JSON Find Response](#json-find-response) example. @@ -520,6 +545,11 @@ Base58 string representation. See [`FindRequest`][find-request-schema] schema. } ``` +##### 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. See [Cascading Lookup](#cascading-lookup) + + ##### Response * `application-json` - JSON encoded [`FindResponse`][find-response-schema]. See [JSON Batch Find Response](#json-batch-find-response) example. @@ -650,6 +680,6 @@ The following lists the libraries and implementations of IPNI protocol: Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). -[find-response-schema]: schemas/v1/openapi.yaml#L108 -[provider-record-schema]: (schemas/v1/openapi.yaml#L124) -[find-request-schema]: schemas/v1/openapi.yaml#L144 +[find-response-schema]: schemas/v1/openapi.yaml#L120 +[provider-record-schema]: (schemas/v1/openapi.yaml#L136) +[find-request-schema]: schemas/v1/openapi.yaml#L156 diff --git a/schemas/v1/openapi.yaml b/schemas/v1/openapi.yaml index 54f8b03..542c145 100644 --- a/schemas/v1/openapi.yaml +++ b/schemas/v1/openapi.yaml @@ -1,7 +1,6 @@ openapi: 3.0.3 info: title: IPNI HTTP API - summary: IPNI HTTP query API description: The Interplanetary Network Indexer (IPNI) HTTP query API. version: 0.0.1 paths: @@ -13,6 +12,7 @@ paths: in: path description: The string representation of the CID. required: true + - $ref: '#/components/parameters/Cascade' responses: '200': description: At least one provider was found successfully. @@ -39,6 +39,12 @@ paths: description: Failure occurred while processing the request. content: text/plain: { } + /cid: + options: + description: Returns permitted communication options for lookup by CID. + responses: + 204: + $ref: '#/components/responses/FindOptions' /multihash/{multihash}: get: description: Finds provider records for a given multihash @@ -47,6 +53,7 @@ paths: in: path description: The base58 string representation of the multihash. required: true + - $ref: '#/components/parameters/Cascade' responses: '200': description: At least one provider was found successfully. @@ -74,6 +81,11 @@ paths: content: text/plain: { } /multihash: + options: + description: Returns permitted communication options for lookup by multihash. + responses: + 204: + $ref: '#/components/responses/FindOptions' post: description: Batch finds provider records for a given set of multihashes requestBody: @@ -236,6 +248,45 @@ components: } ] } + parameters: + Cascade: + name: cascade + in: query + description: | + The comma separated list of routing systems to search for providers in addition to IPNI. + The list of supported routing systems can be discovered by reading `X-IPNI-Allow-Cascade` + response header to `OPTIONS` request. + schema: + type: string + required: false + responses: + FindOptions: + description: Request accepted. + headers: + Access-Control-Allow-Origin: + description: | + The origin permitted to the request. + See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. + schema: + type: string + Access-Control-Allow-Headers: + description: | + The comma separated list of HTTP headers inspected by the server. + See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers + schema: + type: string + Access-Control-Allow-Methods: + description: | + The comma separated list of permitted HTTP methods. + See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method + schema: + type: string + X-IPNI-Allow-Cascade: + description: | + The comma separated list of supported routing systems onto which the lookup can be cascaded. + The absence of this header implies that the server does not offer cascading lookups. + schema: + type: string externalDocs: description: IPNI Specification url: https://github.com/ipni/specs/blob/main/IPNI.md \ No newline at end of file