cleanup

Author: hacdias

src/ipips/ipip-0410.md

@@ -15,8 +15,9 @@ order: 410
 tags: ['ipips']
 ---
 
-Introduce backwards-compatible streaming support to the Routing V1 HTTP API by
-using the HTTP Header `Accept` (:cite[rfc9110]) with [Newline Delimited JSON (NDJSON)](http://ndjson.org/).
+Introduce backwards-compatible streaming support to the Routing V1 HTTP API.
+For this, we use the `Accept` HTTP header (:cite[rfc9110]) for content type negotiation, as well
+as the Newline Delimited JSON ([NDJSON]) format.
 
 ## Motivation
 
@@ -31,22 +32,32 @@ as they are available. This reduces latency and allows for faster content discov
 In addition, streaming responses may produce an unlimited amount of results, which
 is not the case for non-streamed responses.
 
-## Detailed design
+## Detailed Design
 
-In summary, streaming is supported by using the `Accept` HTTP header (:cite[rfc9110])
-along with the `application/x-ndjson` content type. For more details regarding the design,
-check :cite[http-routing-v1].
+In summary, streaming is supported by using the `Accept` HTTP header, which is used
+for content type negotiation as described in :cite[rfc9110]. The client sends an
+`Accept` HTTP header starting with `application/x-ndjson`, which is the content
+type for [NDJSON]. The following happens:
 
-## Design rationale
+- The client adds the `Accept` HTTP header in the request starting with `application/x-ndjson`.
+- The server checks the `Accept` HTTP header from the request and, if it contains
+`application/x-ndjson`, they reply with NDJSON. If they don't support NDJSON, they
+can reply with JSON.
+- The server response MUST contain a `Content-Type` HTTP header indicating the
+response type, which may be either `application/json` for non-streaming responses,
+and `application/x-ndjson` for streamed responses.
 
-The idea is to not break compatibility with existing clients and servers. Therefore,
-we can use the `Accept` HTTP header for content negotiation. If the client supports
-streaming, they can advertise so by including `application/x-ndjson` in the headers.
-If the server supports streaming, the response will have `Content-Type` HTTP header
-of `application/x-ndjson` with a streaming response. Otherwise, it will fall back
-to a pure JSON, non-streamed, response.
+For more details regarding the design, check :cite[http-routing-v1].
 
-### User benefit
+## Design Rationale
+
+This feature is designed such that it does not break compatibility with existing
+clients and servers. The `Accept` HTTP header is OPTIONAL. By default, the server
+MUST respond with `application/json` unless the client explicitly asked for
+`application/x-ndjson`. If the server does not support NDJSON, it is allowed
+to still respond with non-streamed JSON.
+
+### User Benefit
 
 Users (clients) will benefit from this change as the servers will now be able
 to respond more promptly to provider record requests. Instead of waiting for the whole
@@ -67,3 +78,5 @@ Security considerations are equivalent as the ones in :cite[ipip-0337].
 ### Copyright
 
 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+[NDJSON]: http://ndjson.org/