ipip-337: final editorial changes

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
 

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