From 685cb158cfd712c2b286d2d0dcfb84cbac7fcee6 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 23 Nov 2020 17:30:30 -0500 Subject: [PATCH] docs: deprecate some old filter parameters The filtering can be done with the general purpose `filter` query parameter. --- .changelog/9262.txt | 6 ++++++ website/pages/api-docs/catalog.mdx | 12 +++++++++--- website/pages/api-docs/health.mdx | 16 ++++++++++++---- 3 files changed, 27 insertions(+), 7 deletions(-) create mode 100644 .changelog/9262.txt diff --git a/.changelog/9262.txt b/.changelog/9262.txt new file mode 100644 index 000000000..fc93251d5 --- /dev/null +++ b/.changelog/9262.txt @@ -0,0 +1,6 @@ +```release-note:deprecation +api: the `tag`, `node-meta`, and `passing` query parameters for various health and catalog +endpoints are now deprecated. The `filter` query parameter should be used as a replacement +for all of the deprecated fields. The deprecated query parameters will be removed in a future +version of Consul. +``` diff --git a/website/pages/api-docs/catalog.mdx b/website/pages/api-docs/catalog.mdx index 942bdd514..d2728f9ef 100644 --- a/website/pages/api-docs/catalog.mdx +++ b/website/pages/api-docs/catalog.mdx @@ -309,7 +309,9 @@ The table below shows this endpoint's support for `?near=_agent` will use the agent's node for the sort. This is specified as part of the URL as a query parameter. -- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Meta` selector instead. + This parameter will be removed in a future version of Consul. + Specifies a desired node metadata key/value pair of the form `key:value`. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter. @@ -454,7 +456,9 @@ The table below shows this endpoint's support for the datacenter of the agent being queried. This is specified as part of the URL as a query parameter. -- `tag` `(string: "")` - Specifies the tag to filter on. This is specified as part of +- `tag` `(string: "")` **Deprecated** - Use `filter` with the `ServiceTags` selector instead. + This parameter will be removed in a future version of Consul. + Specifies the tag to filter on. This is specified as part of the URL as a query parameter. Can be used multiple times for additional filtering, returning only the results that include all of the tag values provided. @@ -463,7 +467,9 @@ The table below shows this endpoint's support for `?near=_agent` will use the agent's node for the sort. This is specified as part of the URL as a query parameter. -- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead. + This parameter will be removed in a future version of Consul. + Specifies a desired node metadata key/value pair of the form `key:value`. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter. diff --git a/website/pages/api-docs/health.mdx b/website/pages/api-docs/health.mdx index 0f3ac434f..7038d9427 100644 --- a/website/pages/api-docs/health.mdx +++ b/website/pages/api-docs/health.mdx @@ -142,7 +142,9 @@ The table below shows this endpoint's support for `?near=_agent` will use the agent's node for the sort. This is specified as part of the URL as a query parameter. -- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead. + This parameter will be removed in a future version of Consul. + Specifies a desired node metadata key/value pair of the form `key:value`. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter. @@ -232,17 +234,23 @@ The table below shows this endpoint's support for `?near=_agent` will use the agent's node for the sort. This is specified as part of the URL as a query parameter. -- `tag` `(string: "")` - Specifies the tag to filter the list. This is +- `tag` `(string: "")` **Deprecated** - Use `filter` with the `Service.Tags` selector instead. + This parameter will be removed in a future version of Consul. + Specifies the tag to filter the list. This is specified as part of the URL as a query parameter. Can be used multiple times for additional filtering, returning only the results that include all of the tag values provided. -- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead. + This parameter will be removed in a future version of Consul. + Specifies a desired node metadata key/value pair of the form `key:value`. This parameter can be specified multiple times, and will filter the results to nodes with the specified key/value pairs. This is specified as part of the URL as a query parameter. -- `passing` `(bool: false)` - Specifies that the server should return only nodes +- `passing` `(bool: false)` **Deprecated** - Use `filter` with the `Checks.Status` selector instead. + This parameter will be removed in a future version of Consul. + Specifies that the server should return only nodes with all checks in the `passing` state. This can be used to avoid additional filtering on the client side.