diff --git a/src/ipips/ipip-0410.md b/src/ipips/ipip-0410.md index 72914186..bc5fc176 100644 --- a/src/ipips/ipip-0410.md +++ b/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/