ipni / specs

:book: Technical Specification of IPNI Protocols
11 stars 2 forks source link

Propose a concise ndjson response and add OpenAPI specification #10

Closed masih closed 1 year ago

masih commented 1 year ago

The majority of IPNI clients use the single lookup APIs, either /cid/<cid> or /multihash/<multihash>, instead of the batch-find API. All three of the APIs use a uniform response schema, which includes the queried multihash directly in it.

In a case where the request accepts streaming response, using the existing uniform response model becomes inefficient: a response may be flushed multiple times and as is each response would have to include the original multihash.

The changes here propose a new trimmed-down response type when the request accepts application/x-ndjson, made-up of the inner provider record object only for the single multihash lookup APIs. This avoids the need for including the original multihash in every streamed response.

Additionally, document the OpenAPI specification for the IPNI HTTP APIs for better human readability.

Spec rendered.

Fixes #8

willscott commented 1 year ago

unwrapping in the simple find case to be less verbose makes a lot of sense