Make buildRequest method public.

[jmcarp]

Generally, users don't need to call the client's buildRequest method, since it's used internally by generated public methods. However, users may occasionally want to invoke buildRequest directly, analogous to oxide api in the CLI. For example, they may want to use an API endpoint that's not yet supported in the generated client. This patch makes the buildRequest method public by renaming it to BuildRequest.

[sudomateo]

No objections from me. I like the escape hatch `oxide api functionality.

[lgfa29]

I would suggest a new BuildRequest public method that wraps the existing privatebuildRequest. This way we can provide a nicer public API to users where the arguments are defined in a struct instead of spread around several parameters, like:

type Request struct {
	Method string
	URL    string
	Body   io.Reader
	Params map[string]string
	Query  map[string]string
}

func (c *Client) BuildRequest(ctx context.Context, req Request) (*http.Request, error) {
	buildRequest(...)
	// ...
}

We could also go one step further and make the HTTP request and return the *http.Response to users directly. This seems to be a pretty common set of steps after buildRequest is called internally:

	// Create the request
	req, err := c.buildRequest(...)
	if err != nil {
		return nil, fmt.Errorf("error building request: %v", err)
	}

	// Send the request.
	resp, err := c.client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("error sending request: %v", err)
	}
	defer resp.Body.Close()

	// Create and return an HTTPError when an error response code is received.
	if err := NewHTTPError(resp); err != nil {
		return nil, err
	}

	// Decode the body from the response.
	if resp.Body == nil {
		return nil, errors.New("request returned an empty body in the response")
	}

[jmcarp]

Updated, WDYT? I think we can leave error checking and parsing the body to the caller.

[sudomateo]

Thanks for moving the discussion here! I like the updated recommendation personally. It just needs some Go doc comments but I trust you both to finalize the implementation. I have to give a conference talk soon then travel home so ping if needed!

[lgfa29]

Thanks for updating it!