ipip-337: final editorial changes

Author: lidel

IPIP/0337-delegated-routing-http-api.md

@@ -15,14 +15,14 @@ and supporting large content providers is a key strategy for driving down IPFS c
 These providers must handle high volumes of traffic and support many users, so leveraging industry-standard tools and services
 such as HTTP load balancers, CDNs, reverse proxies, etc. is a requirement.
 To maximize compatibility with standard tools, IPFS needs an HTTP API specification that uses standard HTTP idioms and payload encoding.
-The [Reframe spec](https://github.com/ipfs/specs/blob/main/reframe/REFRAME_PROTOCOL.md) for delegated content routing is an experimental attempt at this, 
+The [Reframe spec](https://github.com/ipfs/specs/blob/main/reframe/REFRAME_PROTOCOL.md) for delegated content routing is an experimental attempt at this,
 but it has resulted in a very unidiomatic HTTP API which is difficult to implement and is incompatible with many existing tools.
 The cost of a proper redesign, implementation, and maintenance of Reframe and its implementation is too high relative to the urgency of having a delegated content routing HTTP API.
 
 Note that this does not supplant nor deprecate Reframe. Ideally in the future, Reframe and its implementation would receive the resources needed to map the IDL to idiomatic HTTP,
 and implementations of this spec could then be rewritten in the IDL, maintaining backwards compatibility.
 
-We expect this API to be extended beyond "content routing" in the future, so additional IPIPs may rename this to something more general such as "Delegated Routing HTTP API". 
+We expect this API to be extended beyond "content routing" in the future, so additional IPIPs may rename this to something more general such as "Delegated Routing HTTP API".
 
 ## Detailed design
 
@@ -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
@@ -84,13 +84,14 @@ and increasing data availability.
 #### Backwards Compatibility
 
 IPFS Stewards will implement this API in [go-delegated-routing](https://github.com/ipfs/go-delegated-routing), using breaking changes in a new minor version.
-Because the existing Reframe spec can't be safely used in JavaScript and we won't be investing time and resources into changing the wire format implemented in edelweiss to fix it, 
-the experimental support for Reframe in Kubo will be deprecated in the next release and delegated content routing will subsequently use this HTTP API. 
+Because the existing Reframe spec can't be safely used in JavaScript and we won't be investing time and resources into changing the wire format implemented in edelweiss to fix it,
+the experimental support for Reframe in Kubo will be deprecated in the next release and delegated content routing will subsequently use this HTTP API.
 We may decide to re-add Reframe support in the future once these issues have been resolved.-
 
 #### Forwards Compatibility
 
 Standard HTTP mechanisms for forward compatibility are used:
+
 - The API is versioned using a version number prefix in the path
 - The `Accept` and `Content-Type` headers are used for content type negotiation, allowing for backwards-compatible additions of new MIME types, hypothetically such as:
   - `application/cbor` for binary-encoded responses
@@ -104,8 +105,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`
@@ -66,11 +66,14 @@ Specifications for some transfer protocols are provided in the "Transfer Protoco
 
 ### `GET /routing/v1/providers/{CID}`
 
-- Response codes
-  - `200`: the response body contains 0 or more records
-  - `404`: must be returned if no matching records are found
-  - `422`: request does not conform to schema or semantic constraints
-- Response Body
+#### Response codes
+
+- `200` (OK): the response body contains 0 or more records
+- `404` (Not Found): must be returned if no matching records are found
+- `422` (Unprocessable Entity): request does not conform to schema or semantic constraints
+
+#### Response Body
+
 ```json
 {
     "Providers": [
@@ -83,26 +86,23 @@ Specifications for some transfer protocols are provided in the "Transfer Protoco
 }
 ```
 
-- Response limit: 100 providers
+Response limit: 100 providers
 
 Each object in the `Providers` list is a *read provider record*.
 
 ## Pagination
 
 This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update.
 
-### Implementation Notes
-
-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.
+## Streaming
 
-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.
+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`.
 
 ## 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