docs: fix removed opensearch.BuildRequest reference in v4 upgrade guide (#978)

* docs: fix removed opensearch.BuildRequest reference in v4 upgrade guide

The 4.7.0 migration section and the raw-JSON usage guide told readers to
forward a custom Request.GetRequest to opensearch.BuildRequest, but that helper
was removed in 4.7.0 -- the very release the section documents. Replace it with
a net/http-based before/after example (relative path; the transport prepends
the base URL).

Backport of the v4-applicable portion of the #977 fix from main.

Reported in #977.

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

UPGRADING.md

@@ -168,7 +168,33 @@ GetRequest() (*http.Request, error)
 GetRequest(method string) (*http.Request, error)
 ```
 
-This change is invisible to almost all callers: the typed `Req` structs that the client consumes (e.g. `opensearchapi.SearchReq`, the v5-preview `opensearchapi.IndexReq`) already implement the new signature. Only code that defines a custom type satisfying `opensearch.Request` is affected. If you maintain such a type, add a `method string` parameter and forward it to your underlying `http.NewRequest` call (or `opensearch.BuildRequest`).
+This change is invisible to almost all callers: the typed `Req` structs that the client consumes (e.g. `opensearchapi.SearchReq`, the v5-preview `opensearchapi.IndexReq`) already implement the new signature. Only code that defines a custom type satisfying `opensearch.Request` is affected.
+
+If you maintain such a type, add a `method string` parameter and forward it to your request builder. The `opensearch.BuildRequest` helper that earlier v4 releases exposed for this purpose was **removed in 4.7.0**; construct the request with `net/http` directly instead. Give the path a leading slash (e.g. `/_plugins/my_plugin/status`) -- the transport prepends the base URL by string concatenation, so a path without a leading slash produces a malformed URL.
+
+```go
+// Before (<= 4.6.0): method stored on the struct, built via the removed
+// opensearch.BuildRequest helper (which set Content-Type for a non-nil body).
+func (r customReq) GetRequest() (*http.Request, error) {
+    return opensearch.BuildRequest(r.method, r.path, r.body, nil, nil)
+}
+
+// After (>= 4.7.0): method comes from the caller, built with net/http.
+func (r customReq) GetRequest(method string) (*http.Request, error) {
+    req, err := http.NewRequest(method, r.path, r.body)
+    if err != nil {
+        return nil, err
+    }
+    // BuildRequest set this automatically for a non-nil body; http.NewRequest
+    // does not, so set it here or OpenSearch may reject a JSON body with 400/415.
+    if r.body != nil {
+        req.Header.Set("Content-Type", "application/json")
+    }
+    return req, nil
+}
+```
+
+`opensearch.BuildRequest` also accepted `params map[string]string` and `headers http.Header` arguments. To preserve those, set them on the `*http.Request` after construction: encode params onto `req.URL.RawQuery` (via `url.Values`) and add headers to `req.Header`.
 
 ### Path segment values are percent-encoded
 

guides/json.md

@@ -52,14 +52,27 @@ The `Client.Do()` method accepts `any` for its response parameter, which means p
 First, define a request type that satisfies `opensearch.Request`:
 
 ```go
-	// customReq wraps opensearch.BuildRequest to satisfy the opensearch.Request interface.
+	// customReq builds an *http.Request from a path with a leading slash (e.g.
+	// "/_plugins/my_plugin/status") to satisfy the opensearch.Request interface.
+	// The transport prepends the base URL. method is an HTTP method
+	// (e.g. http.MethodGet) forwarded by the caller.
 	type customReq struct {
 		path string
 		body io.Reader
 	}
 
 	func (r customReq) GetRequest(method string) (*http.Request, error) {
-		return opensearch.BuildRequest(method, r.path, r.body, nil, nil)
+		req, err := http.NewRequest(method, r.path, r.body)
+		if err != nil {
+			return nil, err
+		}
+		// opensearch.BuildRequest set this automatically for a non-nil body;
+		// http.NewRequest does not, so set it here or OpenSearch may reject a
+		// JSON body with 400/415.
+		if r.body != nil {
+			req.Header.Set("Content-Type", "application/json")
+		}
+		return req, nil
 	}
 ```