Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce specification for cascading lookup query parameter #9

Merged
merged 2 commits into from
Jan 31, 2023
Merged

Introduce specification for cascading lookup query parameter #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ef5813
Introduce specification for cascading lookup query parameter
masih Jan 26, 2023
b3060a0
Add support for listing cascade options
masih Jan 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions IPNI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
masih marked this conversation as resolved.
Show resolved Hide resolved

* `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
masih marked this conversation as resolved.
Show resolved Hide resolved

* `application/json` - JSON encoded [`FindResponse`][find-response-schema]. See [JSON Find Response](#json-find-response) example.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
53 changes: 52 additions & 1 deletion schemas/v1/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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