Merge pull request #10169 from hashicorp/dnephin/streaming-docs

docs: add streaming to api-docs

website/content/api-docs/features/blocking.mdx

@@ -82,6 +82,24 @@ cases that must be handled correctly.
   [token bucket](https://en.wikipedia.org/wiki/Token_bucket) with burst of 2 is a simple
   way to achieve this.
 
+## Streaming backend
+
+The streaming backend, first introduced in Consul 1.10, is a replacement for the long
+polling backend.  If streaming is supported by an endpoint, it will be used when either
+the `index` or `cached` query parameters are set.
+
+When streaming is used, the Consul servers publish change events to a topic. Clients
+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 the traditional long polling between clients and servers
+by significantly reducing the quantity of data sent between them, while still allowing
+clients to handle read requests.
+
+While streaming is a significant optimization over long polling, it will not populate the
+`X-Consul-LastContact` or `X-Consul-KnownLeader` response headers, because the required
+data is not available to the client.
+
+
 ## Hash-based Blocking Queries
 
 A limited number of agent endpoints also support blocking however because the

website/content/api-docs/health.mdx

@@ -197,9 +197,9 @@ the following selectors and filter operations being supported:
 | `ServiceTags` | In, Not In, Is Empty, Is Not Empty                 |
 | `Status`      | Equal, Not Equal, In, Not In, Matches, Not Matches |
 
-## List Nodes for Service
+## List Service Instances for Service ((#list-nodes-for-service))
 
-This endpoint returns the nodes providing the service indicated on the path.
+This endpoint returns the service instances providing the service indicated on the path.
 Users can also build in support for dynamic load balancing and other features by
 incorporating the use of health checks.
 
@@ -213,9 +213,14 @@ The table below shows this endpoint's support for
 [agent caching](/api/features/caching), and
 [required ACLs](/api#authentication).
 
-| Blocking Queries | Consistency Modes | Agent Caching        | ACL Required             |
+| Blocking Queries     | Consistency Modes | Agent Caching        | ACL Required             |
-| ---------------- | ----------------- | -------------------- | ------------------------ |
+| -------------------- | ----------------- | -------------------- | ------------------------ |
-| `YES`            | `all`             | `background refresh` | `node:read,service:read` |
+| `YES` <sup>1</sup>   | `all`             | `background refresh` | `node:read,service:read` |
+
+<p>
+ <sup>1</sup>some query parameters will use the
+ <a href="/api/features/blocking#streaming-backend">streaming backend</a>
+</p>
 
 ### Parameters
 
@@ -396,9 +401,9 @@ following selectors and filter operations being supported:
 | `Service.Weights.Passing`                             | Equal, Not Equal                                   |
 | `Service.Weights.Warning`                             | Equal, Not Equal                                   |
 
-## List Nodes for Connect-capable Service
+## List Service Instances for Connect-enabled Service
 
-This endpoint returns the nodes providing a
+This endpoint returns the service instances providing a
 [Connect-capable](/docs/connect) service in a given datacenter.
 This will include both proxies and native integrations. A service may
 register both Connect-capable and incapable services at the same time,
@@ -411,11 +416,11 @@ so this endpoint may be used to filter only the Connect-capable endpoints.
 Parameters and response format are the same as
 [`/health/service/:service`](/api/health#list-nodes-for-service).
 
-## List Nodes for Ingress Gateways Associated to a Service
+## List Service Instances for Ingress Gateways Associated with a Service
 
 -> **1.8.0+:** This API is available in Consul versions 1.8.0 and later.
 
-This endpoint returns the nodes providing a [ingress
+This endpoint returns the service instances providing an [ingress
 gateway](/docs/connect/ingress-gateway) for a service in a given datacenter.
 
 | Method | Path                       | Produces           |
@@ -425,6 +430,10 @@ gateway](/docs/connect/ingress-gateway) for a service in a given datacenter.
 Parameters and response format are the same as
 [`/health/service/:service`](/api/health#list-nodes-for-service).
 
+**Note** that unlike `/health/connect/:service` and `/health/service/:service` this
+endpoint does not support the [streaming backend](/api/features/blocking#streaming-backend).
+
+
 ## List Checks in State
 
 This endpoint returns the checks in the state provided on the path.