chore(ipip-379): final editorials

src/ipips/ipip-0379.md

@@ -20,39 +20,49 @@ tags: ['ipips']
 
 ## Summary
 
-This IPIP specifies a set of HTTP APIs to offload naming system onto another process or server.
+This IPIP specifies `/routing/v1/ipns` HTTP API to offload naming system onto another process or server.
 
 ## Motivation
 
-Expanding on the motivations of :cite[ipip-0337], the work here concentrates on delegation of _naming system_ over HTTP APIs. Naming is part of the core IPFS DHT functionality.
+One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative systems.
+
+Expanding on the motivations of :cite[ipip-0337], the work here concentrates on delegation of IPNS over HTTP API. Naming is part of the core IPFS DHT functionality.
 The performance of naming system over the IPFS DHT can suffer from long delays due to churn of records and quorum requirements.
 
 ## Detailed design
 
-See :cite[http-routing-v1] specification.
+Add `/routing/v1/ipns` to the existing :cite[http-routing-v1] specification.
 
 ## Design rationale
 
 The rationale for delegated IPNS over HTTP APIs closely follows the reasoning listed in :cite[ipip-0337].
 
 The document proposes the following:
-- Use of HTTP semantics for publication and resolution of naming records.
-- Use of existing :ref[IPNS Record] serialization format through `Content-Type: application/vnd.ipfs.ipns-record`.
-- Streaming interaction is not supported.
+- HTTP `GET` and `PUT` semantics for publication and resolution of IPNS records.
+- Use of existing :ref[IPNS Record] serialization format as HTTP `Content-Type` [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record).
 
 ### User benefit
 
-The ability of offload naming onto another process or server via an idiomatic and simple HTTP API opens up an opportunity to not only reduce the burden of naming system management, but also introduce alternative naming systems across other routing systems, namely IPNI.
+The ability to offload naming to another process or server using a simple HTTP
+API brings several benefits:
+
+- It reduces the resource drain on light clients such as JavaScript running on
+  a web page, mobile devices, IoT devices, and gateway HTTP services.
+- It enables scaling of IPNS resolution separately from retrieval and
+  deserialization/verification services.
+- Expands the utility of IPNS beyond IPFS nodes, contributes to its broader
+  adoption and impact by reducing integration costs.
 
 ### Compatibility
 
-See "Compatibility" section of :cite[ipip-0337].
+See the "Compatibility" section of :cite[ipip-0337].
 
 #### Serialization Format
 
-:cite[ipns-record] uses `application/vnd.ipfs.ipns-record` protobuf serialization format.
+Standard IPNS record serialization format is used, making it fully compatible with the existing IPNS ecosystem.
+
+:cite[ipns-record] uses [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) protobuf serialization format.
 This format is widely in use in IPNS over PubSub and DHT routing systems.
-One of the motivations of this document is to introduce simple to use HTTP APIs and ultimately reduce barrier for interaction across alternative systems.
 Further, interoperability across the existing and HTTP APIs is also desirable in order to reduce the barrier for adoption of the delegated HTTP APIs.
 
 To maximize interoperability with existing ecosystem, the canonical IPNS record serialization format :cite[ipns-record] (`0x0300`) can be requested with content type `application/vnd.ipfs.ipns-record`.
@@ -64,14 +74,15 @@ Additionally, the IPNS records must be validated according to the rules stated i
 
 To avoid Denial of Service attack, maximum IPNS record size defined in :cite[ipns-record] applies.
 
-Privacy in delegated IPNS is out of scope for this work.
+Privacy in delegated IPNS is out of scope for this IPIP.
 
 ### Alternatives
 
 See:
-
-- [Libp2p-based IPNS](https://github.com/ipfs/go-ipns).
+- IPNS over (libp2p over HTTP). While it may be possible in the future, it has more narrow utility and way bigger implementation complexity than libp2p-agnostic HTTP API  with protobuf GET/PUT.
 - Reframe; it was deprecated and now removed. Historical reasons can be found in :cite[ipip-0337].
+- JSON IPNS Record representation was descoped due to open question how signing should work and unclear use case ([discussion](https://github.com/ipfs/specs/pull/379#discussion_r1107898543)).
+- API-specific max record size was descoped, as it would introduce interop problems harmful to the IPNS ecosystem.
 
 ### Copyright
 

src/routing/http-routing-v1.md

@@ -67,11 +67,7 @@ Where:
 
 Specifications for some transfer protocols are provided in the "Transfer Protocols" section.
 
-### IPNS Records
-
-:ref[IPNS Records] are serialized using the verifiable [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) format. For more details, read the specification :cite[ipns-record].
-
-## API
+## Content Providers API
 
 ### `GET /routing/v1/providers/{cid}`
 
@@ -103,35 +99,44 @@ Response limit: 100 providers
 
 Each object in the `Providers` list is a *read provider record*.
 
+## IPNS API
+
 ### `GET /routing/v1/ipns/{name}`
 
 #### Path Parameters
 
-- `name` is the :ref[IPNS Name] to resolve.
+- `name` is the :ref[IPNS Name] to resolve, encoded as CIDv1.
 
 #### Response Status Codes
 
 - `200` (OK): the response body contains the :ref[IPNS Record] for the given :ref[IPNS Name].
 - `404` (Not Found): must be returned if no matching records are found.
+- `406` (Not Acceptable): requested content type is missing or not supported. Error message returned in body should inform the user to retry with `Accept: application/vnd.ipfs.ipns-record`.
+
+#### Response Headers
+
+- `Etag`: a globally unique opaque string used for HTTP caching. MUST be derived from the protobuf record returned in the body.
+- `Cache-Control: max-age={TTL}`: cache TTL returned with :ref[IPNS Record] that has `IpnsEntry.data[TTL] > 0`. When present, SHOULD match the TTL value from the record. When record was not found (HTTP 404) or has no TTL (value is `0`), implementation SHOULD default to `max-age=60`.
 
 #### Response Body
 
-The response body contains a [`application/vnd.ipfs.ipns-record`][application/vnd.ipfs.ipns-record] serialized :ref[IPNS Record].
+The response body contains a  :ref[IPNS Record] serialized using the verifiable [`application/vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) protobuf format.
 
 ### `PUT /routing/v1/ipns/{name}`
 
 #### Path Parameters
 
-- `name` is the :ref[IPNS Name] to publish.
+- `name` is the :ref[IPNS Name] to publish, encoded as CIDv1.
 
 #### Request Body
 
-The content body must be a [`application/vnd.ipfs.ipns-record`][application/vnd.ipfs.ipns-record] serialized :ref[IPNS Record], which matches the `name` path parameter.
+The content body must be a [`application/vnd.ipfs.ipns-record`][application/vnd.ipfs.ipns-record] serialized :ref[IPNS Record], with a valid signature matching the `name` path parameter.
 
 #### Response Status Codes
 
 - `200` (OK): the provided :ref[IPNS Record] was published.
 - `400` (Bad Request): the provided :ref[IPNS Record] or :ref[IPNS Name] are not valid.
+- `406` (Not Acceptable): submitted content type is not supported. Error message returned in body should inform the user to retry with `Content-Type: application/vnd.ipfs.ipns-record`.
 
 ## Pagination