docs: Add streaming to api features

This commit is contained in:
Daniel Nephin 2021-05-03 17:27:25 -04:00
parent 979199696b
commit 789478b542
2 changed files with 47 additions and 0 deletions

View file

@ -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

View file

@ -14,6 +14,10 @@
"title": "Blocking Queries", "title": "Blocking Queries",
"path": "features/blocking" "path": "features/blocking"
}, },
{
"title": "Streaming",
"path": "features/streaming"
},
{ {
"title": "Filtering", "title": "Filtering",
"path": "features/filtering" "path": "features/filtering"