please

Please: Ask nicely.

Please is a slightly more idiomatic Golang requests helper that serves as a wrapper around the net/http http.Client. Unlike many other similar projects, it doesn't blindly copy the python-requests API, nor does it provide some of the amenities one might expect from mostly-automatic-HTTP-request-handling. It does support method chaining, and the API attempts to read more politely than most, thereby presenting your maintenance programmer (or future you!) with a happier story when things suddenly stop working as intended.

Why Please?

There are many client libraries for Go that provide a wide array of APIs and philosophical differences ranging from Python-esque to pathologically idiomatic Go. This library hopes to sit somewhere in between these two extremes by providing an easily chainable API that exposes wrapped net/http client types.

If you wish to see an example of Please at work, the currently-a-work-in-progress framework Capstan uses it internally for client-side HTTP unit tests.

Usage

To use Please simply:

$ go get git.destrealm.org/go/please

The Please API is quite simple. Here is a demonstration of a GET request to httpbin.org:

Sample Code

type httpbinJSON struct {
	Args    map[string]string `json:"args,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	Origin  string            `json:"origin,omitempty"`
	URL     string            `json:"url,omitempty"`
	JSON    map[string]string `json:"json,omitempty"`
}

func Get() error {
    var data httpbinJSON

    // Create the request.
    request := please.Get("http://httpbin.org/get")

    // Send the request and retrieve the response.
    //
    // .Request() is required after .Add() to retrieve the underlying request
    // instance, otherwise multiple .Add()s may be chained together.
    response, err := request.Query().Add("sample", "value").Request().Send()
    if err != nil {
        return err
    }

    // Load the response into a pointer to `data`.
    if err := response.JSON(&data); err != nil {
        return err
    }

    fmt.Printf("received: %v\n", data)
}

As you can see, while the API isn't as simple as many other competing libraries, the calls between creating the client request and calling request.Send() provide a fair bit of flexibility without requiring varargs or passing around interfaces. Because Please is mostly a convenience wrapper around http.Client, it's trivial to leverage existing functionality without relying on too magic. Leastwise, the magic that exists outside mildly excessive method chaining.

More Work to be Done!

Nevertheless, Please requires much more work to be done. In particular, API documentation needs to be written, and some internal refactoring certainly couldn't hurt.

Once you've submitted the request via Send, Please does provide a couple of conveniences:

• Headers() returns the http.Header associated with the response.
• JSON() reads the response into a JSON-tagged struct, provided the response contains valid JSON.
• ReadAll() reads the entire response body.
• Body() provides an io.Reader to read the response body if you have a need that isn't completely fulfilled with ReadAll().

Prior to commit, there are:

• Form() returns a pointer to the form values to send with the request. Only works with POST-compatible queries (POST and PUT mostly). Otherwise any values set via this method will be ignored.
• Headers() returns a pointer to the request headers for manipulation prior to the request.
• Query() returns a pointer to a url.Values instance that can be modified to add or remove query string values.
• WriteJSON() accepts an interface that must be a JSON-tagged struct to be converted into a JSON request body.

We also have available the option to add "code handlers," which are functions that are called based upon the response code returned by the server. These can be assigned via On() or applied broadly using Each(). As with many of the features mentioned above, code handlers need further documentation!

For more examples, please refer to the request-cycle unit tests.

License

Please is offered under the terms of the NCSA license. This is a liberal license that allows for commercial use provided attribution is given. Additionally, and somewhat distinctly from similar licenses (BSD and MIT in particular), this license also extends to documentation included with the distribution.

Copyright

Copyright (c) 2021 Benjamin A. Shelton.