v3 docs: Describe syntax & patterns for query parameters

- Add a new "Query Parameters" section under "Concepts"
- Call out encoding of commas in query param values (must be encoded
twice if they appear in list values, e.g. `names=a%2Cb` for a resource
named `a,b`).

[finishes #173720501]

Authored-by: Reid Mitchell <rmitchell@pivotal.io>

Author: reidmit

docs/v3/source/includes/concepts/_filters.md.erb

@@ -1,7 +1,8 @@
 ## Filters
 
-Endpoints which return lists of resources also support filtering the returned resources using query parameters.
-The available filter parameters are described in a resource's "list" endpoint in the section "Query parameters".
+Endpoints which return lists of resources also support filtering the returned resources using query parameters. Each
+resource's list endpoint documents the allowed filters for that endpoint. For details about the syntax of query parameters
+in general, see [query parameters](#query-parameters).
 
 #### Examples
 

docs/v3/source/includes/concepts/_query_parameters.md.erb

@@ -0,0 +1,8 @@
+## Query Parameters
+
+Clients can assume that query parameters on the API will always follow these rules:
+
+- Parameter names (before the `=`, and ignoring any modifiers like `[gt]`) will only contain characters `a-z` (lowercase) and `-`.
+- When a parameter accepts multiple values, these will be represented as a comma-delimited list of strings (see [filters](#filters)).
+
+Because commas are used to separate list entries, **parameter values that contain commas must be percent-encoded**. For example, to retrieve apps named either `a,b` or `c,d`, the request would look like `GET /v3/apps?names=a%2Cb,c%2Cd`. Note that the commas within the app names are encoded (as `%2C`), but the comma separating the two app names is not. If a client is encoding the whole query string before sending it to the API, the commas within the app names will end up double-encoded.

docs/v3/source/index.md

@@ -53,6 +53,7 @@ includes:
   - concepts/metadata
   - concepts/pagination
   - concepts/procfiles
+  - concepts/query_parameters
   - concepts/relationships
   - concepts/status_codes
   - concepts/timestamps