requests Go Library

The core of the library is the requests.Builder type, which provides a fluent API for building and sending HTTP requests. Instead of the verbose boilerplate required by net/http, you use method chaining to declaratively describe your request.

Key characteristics:

• Fluent API: Methods return a pointer to the same builder, allowing chaining.
• Automatic Resource Management: It automatically handles closing the response body.
• Default Validation: It checks that response status codes are in the 2XX range by default.
• Context Required: Every request must be executed using .Fetch(ctx), where ctx is a context.Context.

err := requests.
	URL("http://example.com").
	ToString(&s).
	Fetch(ctx)

A BodyGetter is a function type used by request builders to provide a source for the request body. It returns an io.ReadCloser and an error. This abstraction allows the request to lazily open and read the body content only when the request is actually executed.

Common ways to create a BodyGetter include using raw bytes, files, JSON, or form data.

The ParamOptional method allows you to define query parameters that should only be included in the final URL if they are not already present. This is useful for setting default values or avoiding overwriting existing parameters when building URLs from a base.

• If the key is already present in the query string, ParamOptional does nothing.
• If the key is not present and the provided values are not empty, the parameter is added.
• If the key is not present but the provided values are empty, nothing is added.

To send a POST request with a raw byte slice as the body, use .BodyBytes([]byte) and set the content type using .ContentType("type").

err := requests.
	URL("https://postman-echo.com/post").
	BodyBytes([]byte(`hello, world`)).
	ContentType("text/plain").
	Fetch(ctx)

The builder allows you to modify parts of the URL before the request is sent. You can change the host with .Hostf(format, ...) and add query parameters using .Param(key, value) or .ParamInt(key, int). Call .URL() to retrieve the constructed *url.URL object.

u, err := requests.
	URL("https://prod.example.com/get?a=1&b=2").
	Hostf("%s.example.com", "dev1").
	Param("b", "3").
	ParamInt("c", 4).
	URL()
if err != nil { /* ... */ }
fmt.Println(u.String()) // https://dev1.example.com/get?a=1&b=3&c=4

Use .Header(key, value) for arbitrary headers, or convenience methods like .UserAgent(string) and .ContentType(string).

// Set headers
var headers postman
err := requests.
	URL("https://postman-echo.com/get").
	UserAgent("bond/james-bond").
	ContentType("secret").
	Header("martini", "shaken").
	Fetch(ctx)

To fetch a JSON response and unmarshal it into a Go struct, use .ToJSON(&struct).

var post placeholder
err := requests.
	URL("https://jsonplaceholder.typicode.com").
	Pathf("/posts/%d", 1).
	ToJSON(&post).
	Fetch(ctx)

Use the reqtest package (part of the requests ecosystem) to record real HTTP interactions to the file system and replay them in subsequent test runs. This is useful for creating deterministic tests without hitting live endpoints.

1. Record: Use reqtest.Record(nil, "directory") in the .Transport() method.
2. Replay: Use reqtest.Replay("directory") in the .Transport() method.

// record a request to the file system
var s1, s2 string
err := requests.URL("http://example.com").
	Transport(reqtest.Record(nil, "somedir")).
	ToString(&s1).
	Fetch(ctx)
check(err)

// now replay the request in tests
err = requests.URL("http://example.com").
	Transport(reqtest.Replay("somedir")).
	ToString(&s2).
	Fetch(ctx)
check(err)
assert(s1 == s2) // true

To fetch the body of a GET request and store it in a string variable, use the .ToString(&variable) method before calling .Fetch(ctx).

var s string
err := requests.
	URL("http://example.com").
	ToString(&s).
	Fetch(ctx)

You can chain .BodyJSON(&requestStruct) to send a JSON payload and .ToJSON(&responseStruct) to parse the resulting response in a single chain.

var res placeholder
req := placeholder{
	Title:  "foo",
	Body:   "baz",
	UserID: 1,
}
err := requests.
	URL("/posts").
	Host("jsonplaceholder.typicode.com").
	BodyJSON(&req).
	ToJSON(&res).
	Fetch(ctx)