Filter API Docs (#9202)

* reorganize for clarity and update for value syntax * fix quotes around value * Apply suggestions from code review Co-authored-by: Blake Covarrubias <blake@covarrubi.as> * Apply suggestions from code review Co-authored-by: Freddy <freddygv@users.noreply.github.com> Co-authored-by: Blake Covarrubias <blake@covarrubi.as> Co-authored-by: Freddy <freddygv@users.noreply.github.com>
hashicorp · Dec 9, 2020 · a042b74 · a042b74
1 parent aa03e99
commit a042b74
Showing 1 changed file with 60 additions and 56 deletions.
diff --git a/website/pages/api-docs/features/filtering.mdx b/website/pages/api-docs/features/filtering.mdx
@@ -9,83 +9,48 @@ description: |-
 
 # Filtering
 
-A filter expression is used to refine a data query for some API listing endpoints as notated in the individual API documentation.
-Filtering will be executed on the Consul server before data is returned, reducing the network load. To pass a
-filter expression to Consul, with a data query, use the `filter` parameter.
+Filter expressions refine data queries for some API listing endpoints, as notated in the individual API documentation.
+
+To create a filter expression, you will write one or more expressions. Each expression has a matching operators composed with selectors and values.
 
 ```shell
-curl -G <path> --data-urlencode 'filter=<filter expression>'
+curl --get <path> --data-urlencode 'filter="<filter expression>"'
 ```
 
-To create a filter expression, you will write one or more expressions using matching operators, selectors, and values.
+Filtering is executed on the Consul server, before data is returned, reducing the network load. To pass a
+filter expression to Consul, use the `filter` query parameter when sending requests to HTTP API endpoints that support it.
 
-## Expression Syntax
+## Creating Expressions
 
-Expressions are written in plain text format. Boolean logic and parenthesization are
+A single expression is a matching operator with a selector and value. They are written in plain text format, boolean logic and parenthesization are
 supported. In general whitespace is ignored, except within literal
 strings.
 
-### Expressions
-
-There are several methods for connecting expressions, including
-
-- logical `or`
-- logical `and`
-- logical `not`
-- grouping with parenthesis
-- matching expressions
-
-```text
-// Logical Or - evaluates to true if either sub-expression does
-<Expression 1> or <Expression 2>
-
-// Logical And - evaluates to true if both sub-expressions do
-<Expression 1 > and <Expression 2>
-
-// Logical Not - evaluates to true if the sub-expression does not
-not <Expression 1>
-
-// Grouping - Overrides normal precedence rules
-( <Expression 1> )
-
-// Inspects data to check for a match
-<Matching Expression 1>
-```
-
-Standard operator precedence can be expected for the various forms. For
-example, the following two expressions would be equivalent.
-
-```text
-<Expression 1> and not <Expression 2> or <Expression 3>
-
-( <Expression 1> and (not <Expression 2> )) or <Expression 3>
-```
-
 ### Matching Operators
 
-Matching operators are used to create an expression. All matching operators use a selector or value to choose what data should be
+All matching operators use a selector or value to choose what data should be
 matched. Each endpoint that supports filtering accepts a potentially
 different list of selectors and is detailed in the API documentation for
 those endpoints.
 
 ```text
 // Equality & Inequality checks
-<Selector> == <Value>
-<Selector> != <Value>
+<Selector> == "<Value>"
+<Selector> != "<Value>"
 
 // Emptiness checks
 <Selector> is empty
 <Selector> is not empty
 
 // Contains checks or Substring Matching
-<Value> in <Selector>
-<Value> not in <Selector>
-<Selector> contains <Value>
-<Selector> not contains <Value>
+"<Value>" in <Selector>
+"<Value>" not in <Selector>
+<Selector> contains "<Value>"
+<Selector> not contains "<Value>"
 
 // Regular Expression Matching
-<Selector> matches <Value>
-<Selector> not matches <Value>
+<Selector> matches "<Value>"
+<Selector> not matches "<Value>"
 ```
 
 ### Selectors
@@ -108,12 +73,51 @@ ServiceMeta["foo"]
 
 ### Values
 
-Values are used by matching operators to create an expression. Values can be any valid selector, a number, or a quoted string. For numbers any
-base 10 integers and floating point numbers are possible. For quoted strings,
+Values are used by matching operators to create an expression. Values can be any valid selector, a number, or a string. It is best practice to quote values. 
+
+Numbers can be base 10 integers or floating point numbers. 
+
+When quoting strings,
 they may either be enclosed in double quotes or backticks. When enclosed in
 backticks they are treated as raw strings and escape sequences such as `\n`
 will not be expanded.
 
+## Connecting Expressions
+
+There are several methods for connecting expressions, including
+
+- logical `or`
+- logical `and`
+- logical `not`
+- grouping with parenthesis
+- matching expressions
+
+```text
+// Logical Or - evaluates to true if either sub-expression does
+<Expression 1> or <Expression 2>
+
+// Logical And - evaluates to true if both sub-expressions do
+<Expression 1 > and <Expression 2>
+
+// Logical Not - evaluates to true if the sub-expression does not
+not <Expression 1>
+
+// Grouping - Overrides normal precedence rules
+( <Expression 1> )
+
+// Inspects data to check for a match
+<Matching Expression 1>
+```
+
+Standard operator precedence can be expected for the various forms. For
+example, the following two expressions would be equivalent.
+
+```text
+<Expression 1> and not <Expression 2> or <Expression 3>
+
+( <Expression 1> and (not <Expression 2> )) or <Expression 3>
+```
+
 ## Filter Utilization
 
 Generally, only the main object is filtered. When filtering for
@@ -195,7 +199,7 @@ curl -X GET localhost:8500/v1/agent/services
 **Command - Filtered**
 
 ```shell
-curl -G localhost:8500/v1/agent/services --data-urlencode 'filter=Meta.env == qa'
+curl --get localhost:8500/v1/agent/services --data-urlencode 'filter=Meta.env == "qa"'
 ```
 
 **Response - Filtered**
@@ -326,7 +330,7 @@ curl -X GET localhost:8500/v1/catalog/service/api-internal
 **Command - Filtered**
 
 ```shell
-curl -G localhost:8500/v1/catalog/service/api-internal --data-urlencode 'filter=NodeMeta.os == linux'
+curl --get localhost:8500/v1/catalog/service/api-internal --data-urlencode 'filter=NodeMeta.os == "linux"'
 ```
 
 **Response - Filtered**