From e93e7d015258c9b963e9013fd963e25c04be037f Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Mon, 3 May 2021 17:27:25 -0400
Subject: [PATCH] docs: Add streaming to api features

---
 .../content/api-docs/features/streaming.mdx   | 43 +++++++++++++++++++
 website/data/api-docs-nav-data.json           |  4 ++
 2 files changed, 47 insertions(+)
 create mode 100644 website/content/api-docs/features/streaming.mdx

diff --git a/website/content/api-docs/features/streaming.mdx b/website/content/api-docs/features/streaming.mdx
new file mode 100644
index 0000000000..8a2c912d0f
--- /dev/null
+++ b/website/content/api-docs/features/streaming.mdx
@@ -0,0 +1,43 @@
+---
+layout: api
+page_title: Streaming
+description: |-
+  Some API endpoints support a feature known as "streaming". Change events
+  are published to a stream topic, allowing clients to build a localized
+  view, and removing the need to send full state-of-the-world responses
+  every time data changes.
+---
+
+# Streaming
+
+A few endpoints in Consul support a feature known as "streaming". With streaming
+the Consul servers publish change events to a topic. Clients can subscribe to a
+topic to receive these change events. The clients use the change events to build
+a local "materialized view". Clients are then able to handle requests using that view.
+Streaming improves on [blocking queries][1] by significantly reducing the quantity
+of data sent from servers to clients, while still allowing clients to handle
+read requests.
+
+Streaming, first introduced in Consul 1.10, is a replacement for [blocking queries][1],
+and is only supported by a small number of endpoints. If streaming is supported by an
+endpoint, it will be used when either the `index` or `cached` query parameters are set.
+
+Endpoints that support streaming return an HTTP header named
+`X-Consul-Index`. This is a unique identifier representing the current state of
+the requested resource.
+
+On subsequent requests for this resource, the client can set the `index` query
+string parameter to the value of `X-Consul-Index`, indicating that the client
+wishes to wait for any changes subsequent to that index.
+
+When `index` is set, the HTTP request will "hang" until a change in the system
+occurs, or the maximum timeout is reached. A critical note is that the return of
+a blocking request is **no guarantee** of a change. It is possible that the
+timeout was reached or that there was an idempotent write that does not affect
+the result of the query.
+
+Note that streaming does not support all query parameters used by blocking queries, and
+that some response headers (ex: `X-Consul-LastContact` and `X-Consul-KnownLeader`) are not
+set because the data is not available.
+
+[1]: /api-docs/features/blocking
diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json
index 4f1688f561..2cf6017b9c 100644
--- a/website/data/api-docs-nav-data.json
+++ b/website/data/api-docs-nav-data.json
@@ -14,6 +14,10 @@
         "title": "Blocking Queries",
         "path": "features/blocking"
       },
+      {
+        "title": "Streaming",
+        "path": "features/streaming"
+      },
       {
         "title": "Filtering",
         "path": "features/filtering"