Rename WithCustomQueryParameters => WithQueryParameters (hashicorp#217)

* Rename WithCustomQueryParameters => WithQueryParameters

* format readme

* fix TOC link

* pr feedback

* toc

Author: averche

README.md

@@ -23,7 +23,7 @@ A simple [HashiCorp Vault][vault] Go client library.
    - [Using Generated Methods](#using-generated-methods)
    - [Modifying Requests](#modifying-requests)
      - [Overriding Default Mount Path](#overriding-default-mount-path)
-     - [Adding Custom Headers and Custom Query Parameters](#adding-custom-headers-and-custom-query-parameters)
+     - [Adding Custom Headers and Appending Query Parameters](#adding-custom-headers-and-appending-query-parameters)
      - [Response Wrapping \& Unwrapping](#response-wrapping--unwrapping)
    - [Error Handling](#error-handling)
    - [Using TLS](#using-tls)
@@ -234,9 +234,11 @@ secret, err := client.Secrets.KvV2Read(
 )
 ```
 
-#### Adding Custom Headers and Custom Query Parameters
+#### Adding Custom Headers and Appending Query Parameters
 
-The library allows adding custom headers and query parameters to all requests:
+The library allows adding custom headers and appending query parameters to all
+requests. `vault.WithQueryParameters` is primarily intended for the generic
+`client.Read`, `client.ReadRaw`, `client.List`, and `client.Delete`:
 
 ```go
 resp, err := client.Read(
@@ -246,7 +248,7 @@ resp, err := client.Read(
         "x-test-header1": {"a", "b"},
         "x-test-header2": {"c", "d"},
     }),
-    vault.WithCustomQueryParameters(url.Values{
+    vault.WithQueryParameters(url.Values{
         "param1": {"a"},
         "param2": {"b"},
     }),

api_auth.go

@@ -31,9 +31,9 @@ func (c *Client) Read(ctx context.Context, path string, options ...RequestOption
 		c,
 		http.MethodGet,
 		v1Path(path),
-		nil,                                    // request body
-		requestModifiers.customQueryParameters, // request query parameters
-		requestModifiers,                       // request modifiers (headers & callbacks)
+		nil, // request body
+		requestModifiers.additionalQueryParameters,
+		requestModifiers,
 	)
 }
 
@@ -53,9 +53,9 @@ func (c *Client) ReadRaw(ctx context.Context, path string, options ...RequestOpt
 		c,
 		http.MethodGet,
 		v1Path(path),
-		nil,                                    // request body
-		requestModifiers.customQueryParameters, // request query parameters
-		requestModifiers,                       // request modifiers (headers & callbacks)
+		nil, // request body
+		requestModifiers.additionalQueryParameters,
+		requestModifiers,
 	)
 }
 
@@ -87,9 +87,9 @@ func (c *Client) WriteFromReader(ctx context.Context, path string, body io.Reade
 		c,
 		http.MethodPost,
 		v1Path(path),
-		body,                                   // request body
-		requestModifiers.customQueryParameters, // request query parameters
-		requestModifiers,                       // request modifiers (headers & callbacks)
+		body,
+		requestModifiers.additionalQueryParameters,
+		requestModifiers,
 	)
 }
 
@@ -100,17 +100,17 @@ func (c *Client) List(ctx context.Context, path string, options ...RequestOption
 		return nil, err
 	}
 
-	requestQueryParameters := requestModifiers.customQueryParametersOrDefault()
+	requestQueryParameters := requestModifiers.additionalQueryParametersOrDefault()
 	requestQueryParameters.Add("list", "true")
 
 	return sendRequestParseResponse[map[string]interface{}](
 		ctx,
 		c,
 		http.MethodGet,
 		v1Path(path),
-		nil,                    // request body
-		requestQueryParameters, // request query parameters
-		requestModifiers,       // request modifiers (headers & callbacks)
+		nil, // request body
+		requestQueryParameters,
+		requestModifiers,
 	)
 }
 
@@ -126,9 +126,9 @@ func (c *Client) Delete(ctx context.Context, path string, options ...RequestOpti
 		c,
 		http.MethodDelete,
 		v1Path(path),
-		nil,                                    // request body
-		requestModifiers.customQueryParameters, // request query parameters
-		requestModifiers,                       // request modifiers (headers & callbacks)
+		nil, // request body
+		requestModifiers.additionalQueryParameters,
+		requestModifiers,
 	)
 }
 

api_identity.go

@@ -35,7 +35,7 @@ func ({{lower (substring classname 0 1)}} *{{cut classname "Api"}}) {{nickname}}
 	requestPath = strings.Replace(requestPath, "{"+"{{baseName}}"+"}", url.PathEscape(requestModifiers.mountPathOr({{#with defaultValue}}{{{.}}}{{/with}})), -1){{/endsWith}}{{/each}}{{#each pathParams}}{{#endsWith baseName "_mount_path"}}{{else}}
     requestPath = strings.Replace(requestPath, "{"+"{{baseName}}"+"}", url.PathEscape({{paramName}}), -1){{/endsWith}}{{/each}}
 
-	requestQueryParameters := requestModifiers.customQueryParametersOrDefault()
+	requestQueryParameters := requestModifiers.additionalQueryParametersOrDefault()
 {{~#each queryParams}}
 {{~#eq paramName "list"}}
 	requestQueryParameters.Add("{{baseName}}", "true")

api_secrets.go

@@ -28,12 +28,12 @@ type requestModifiers struct {
 	responseCallbacks []ResponseCallback
 
 	// mountPath, if specified, will overwrite the default mount path used in
-	// client.Auth & client.Secrets requests
+	// client.Auth & client.Secrets requests.
 	mountPath string
 
-	// customQueryParameters, if specified will be appended to the list of
-	// query parameters included with the request
-	customQueryParameters url.Values
+	// additionalQueryParameters, if specified will be appended to the list of
+	// query parameters included with the request.
+	additionalQueryParameters url.Values
 }
 
 // requestHeaders contains headers that will be added to requests
@@ -237,12 +237,12 @@ func (m *requestModifiers) mountPathOr(defaultMountPath string) string {
 	return m.mountPath
 }
 
-// customQueryParametersOrDefault returns object's query parameters or an empty map.
-func (m *requestModifiers) customQueryParametersOrDefault() url.Values {
-	if m.customQueryParameters == nil {
+// additionalQueryParametersOrDefault returns object's query parameters or an empty map.
+func (m *requestModifiers) additionalQueryParametersOrDefault() url.Values {
+	if m.additionalQueryParameters == nil {
 		return make(url.Values)
 	}
-	return m.customQueryParameters
+	return m.additionalQueryParameters
 }
 
 // mergeRequestModifiers merges the two objects, preferring the per-request modifiers

api_system.go

@@ -115,10 +115,12 @@ func WithMountPath(path string) RequestOption {
 	}
 }
 
-// WithCustomQueryParameters appends the given list of query parameters to the request.
-func WithCustomQueryParameters(parameters url.Values) RequestOption {
+// WithQueryParameters appends the given list of query parameters to the request.
+// This is primarily intended to be used with client.Read, client.ReadRaw,
+// client.List, and client.Delete methods.
+func WithQueryParameters(parameters url.Values) RequestOption {
 	return func(m *requestModifiers) error {
-		m.customQueryParameters = parameters
+		m.additionalQueryParameters = parameters
 		return nil
 	}
 }