diff --git a/IPIP/0337-delegated-routing-http-api.md b/IPIP/0337-delegated-routing-http-api.md index 2325a734e..be6852aae 100644 --- a/IPIP/0337-delegated-routing-http-api.md +++ b/IPIP/0337-delegated-routing-http-api.md @@ -62,7 +62,7 @@ So this API proposal makes the following changes: - The Delegated Content Routing API is defined using HTTP semantics, and can be implemented without introducing Reframe concepts nor IPLD - There is a clear distinction between the RPC protocol (HTTP) and the API (Deleged Content Routing) - "Method names" and cache-relevant parameters are pushed into the URL path -- Streaming support is removed, and default response size limits are added along with an optional `pageLimit` parameter for clients to specify response sizes +- Streaming support is removed, and default response size limits are added. - We will add streaming support in a subsequent IPIP, but we are trying to minimize the scope of this IPIP to what is immediately useful - Bodies are encoded using idiomatic JSON, instead of using IPLD codecs, and are compatible with OpenAPI specifications - The JSON uses human-readable string encodings of common data types @@ -104,8 +104,9 @@ As a proof-of-concept, the tests for the initial implementation of this HTTP API ### Security -- TODO: cover user privacy -- TODO: parsing best practices: what are limits (e.g., per message / field)? +- All CID requests are sent to a central HTTPS endpoint as plain text, with TLS being the only protection against third-party observation. +- While privacy is not a concern in the current version, plans are underway to add a separate endpoint that prioritizes lookup privacy. Follow the progress in related pre-work in [IPIP-272 (double hashed DHT)](https://github.com/ipfs/specs/pull/373/) and [ipni#5 (reader privacy in indexers)](https://github.com/ipni/specs/pull/5). +- The usual JSON parsing rules apply. To prevent potential Denial of Service (DoS) attack, clients should ignore responses larger than 100 providers and introduce a byte size limit that is applicable to their use case. ### Alternatives diff --git a/routing/DELEGATED_CONTENT_ROUTING_HTTP.md b/routing/DELEGATED_CONTENT_ROUTING_HTTP.md index f3cfada8c..630fa276f 100644 --- a/routing/DELEGATED_CONTENT_ROUTING_HTTP.md +++ b/routing/DELEGATED_CONTENT_ROUTING_HTTP.md @@ -1,6 +1,6 @@ # Delegated Content Routing HTTP API -![wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Delegated Content Routing HTTP API +![reliable](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) Delegated Content Routing HTTP API **Author(s)**: @@ -54,7 +54,7 @@ Both read and write provider records have a minimal required schema as follows: Where: -- `Protocol` is the multicodec name of the transfer protocol +- `Protocol` is the multicodec name of the transfer protocol or an opaque string (for experimenting with novel protocols without a multicodec) - `Schema` denotes the schema to use for encoding/decoding the record - This is separate from the `Protocol` to allow this HTTP API to evolve independently of the transfer protocol - Implementations should switch on this when parsing records, not on `Protocol` @@ -91,18 +91,16 @@ Each object in the `Providers` list is a *read provider record*. This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update. -### Implementation Notes +## Streaming -Servers are required to return *at most* `pageLimit` results in a page. It is recommended for pages to be as dense as possible, but it is acceptable for them to return any number of items in the closed interval [0, pageLimit]. This is dependent on the capabilities of the backing database implementation. -For example, a query specifying a `transfer` filter for a rare transfer protocol should not *require* the server to perform a very expensive database query for a single request. Instead, this is left to the server implementation to decide based on the constraints of the database. +This API does not currently support streaming, however it can be added in the future through a backwards-compatible update by using a content type other than `application/json`. -Implementations should encode into the token whatever information is necessary for fetching the next page. This could be a base32-encoded JSON object like `{"offset":3,"limit":10}`, an object ID of the last scanned item, etc. ## Error Codes -- `501`: must be returned if a method/path is not supported -- `429`: may be returned to indicate to the caller that it is issuing requests too quickly -- `400`: must be returned if an unknown path is requested +- `501` (Not Implemented): must be returned if a method/path is not supported +- `429` (Too Many Requests): may be returned along with optional [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to indicate to the caller that it is issuing requests too quickly +- `400` (Bad Request): must be returned if an unknown path is requested ## CORS and Web Browsers