Easier to use and slightly more idiomatic Golang HTTP client wrapper. Similar to python-requests but contains more primitives and is more Go-like. Ask nicely!
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Benjamin Shelton 508ae8b4e2 Attached appropriate header when calling WriteJSON(). 1 month ago
LICENSE New year. 1 month ago
Makefile Removed unnecessary tags. 1 month ago
README.md Added README. 1 month ago
errors.go Rehome project. 1 month ago
go.mod Rehome project. 1 month ago
go.sum Added go modules. 6 months ago
request.go Attached appropriate header when calling WriteJSON(). 1 month ago
request_test.go Rehome project and switch unit tests to httpbin.org. 1 month ago

README.md

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.

The Please API is nevertheless quite simple. Here is a demonstration of a GET request:

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

    pl := please.MakeRequest("http://httpbin.org")
    request := pl.Get("/get")
    request.Query().Add("sample", "value")

    response, err := request.Commit()
    if err != nil {
        return err
    }

    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 pl and calling request.Commit() 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 magic.

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. Most especially, the ClientRequest.Commit() function should have its logic moved--perhaps to a NewClientRequest() function--such that Commit() does more or less what it says on the box: Commit the request.

Once you've committed the request, 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.

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).
  • 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!