requests

README

requests

An elegant and simple HTTP client package, which learned a lot from the well-known Python package Requests: HTTP for Humans™.

Why not just use the standard library HTTP client?

Brad Fitzpatrick, long time maintainer of the net/http package, wrote Problems with the net/http Client API. The four main points are:

• Too easy to not call Response.Body.Close.
• Too easy to not check return status codes
• Context support is oddly bolted on
• Proper usage is too many lines of boilerplate

requests solves these issues by:

• always closing the response body,
• checking status codes by default,
• optional context.Context parameter,
• and simplifying the boilerplate.

Features

• Keep-Alive & Connection Pooling
• International Domains and URLs
• Sessions with Cookie Persistence
• Browser-style SSL Verification
• Automatic Content Decoding
• Basic/Digest Authentication
• Elegant Key/Value Cookies
• Automatic Decompression
• Unicode Response Bodies
• HTTP(S) Proxy Support
• Multipart File Uploads
• Streaming Downloads
• Connection Timeouts
• Chunked Requests
• .netrc Support

Examples

Simple GET into a text string

code with net/http	code with requests
req, err := http.NewRequestWithContext( ctx, http.MethodGet, "http://example.com", nil) if err != nil { // ... } res, err := http.DefaultClient.Do(req) if err != nil { // ... } defer res.Body.Close() b, err := io.ReadAll(res.Body) if err != nil { // ... } s := string(b)	var txt string r, err := requests.Get("http://example.com") requests.ToText(&txt)) if err != nil { // ... }
14+ lines	5 lines

POST a raw body

code with net/http	code with requests
body := bytes.NewReader(([]byte(`hello, world`)) req, err := http.NewRequestWithContext( ctx, http.MethodPost, "http://example.com", body) if err != nil { // ... } req.Header.Set("Content-Type", "text/plain") res, err := http.DefaultClient.Do(req) if err != nil { // ... } defer res.Body.Close() _, err := io.ReadAll(res.Body) if err != nil { // ... }	r, err := requests.Post("http://example.com", requests.Data(`hello, world`)) if err != nil { // ... }
15+ lines	4+ lines

GET a JSON object

code with net/http	code with requests
u, err := url.Parse("http://example.com") if err != nil { // ... } req, err := http.NewRequestWithContext( ctx, http.MethodGet, u.String(), nil) if err != nil { // ... } resp, err := http.DefaultClient.Do(req) if err != nil { // ... } defer resp.Body.Close() b, err := io.ReadAll(res.Body) if err != nil { // ... } var res JSONResponse err := json.Unmarshal(b, &res) if err != nil { // ... }	var res JSONResponse r, err := requests.Post("http://example.com") requests.ToJSON(&res)) if err != nil { // ... }
22+ lines	5 lines

POST a JSON object and parse the response

req := JSONRequest{
    Title:  "foo",
    Body:   "baz",
    UserID: 1,
}
var res JSONResponse
r, err := requests.Post("http://example.com",
            requests.JSON(&req),
            requests.ToJSON(&res))
if err != nil {
    // ...
}

Set custom header and form for a request

// Set headers and forms
r, err := requests.Post("http://example.com", 
            requests.HeaderPairs("martini", "shaken"),
            requests.FormPairs("name", "Jacky"))
if err != nil {
    // ...
}

Easily manipulate URLs and query parameters

// Set parameters
r, err := requests.Get("http://example.com?a=1&b=2", 
            requests.ParamPairs("c", "3"))
if err != nil { /* ... */ }
// URL: http://example.com?a=1&b=2&c=3

Dump outgoing client request and response

var reqDump, respDump string
r, err := requests.Get("http://example.com", 
            requests.Dump(&request, &respDump))

Documentation

Overview

Package requests is an elegant and simple HTTP library for golang, built for human beings.

This package mimics the implementation of the classic Python package Requests(https://requests.readthedocs.io/)

Index

• func SetEnvTimeout(timeout time.Duration)
• type Option
  • func BasicAuth(username, password string) Option
  • func Body(body io.Reader) Option
  • func Data(data any) Option
  • func DisableKeepAlives() Option
  • func Dump(req, resp *string) Option
  • func Files(files map[string]*os.File) Option
  • func Form(form map[string]string) Option
  • func FormPairs(kv ...string) Option
  • func HeaderPairs(kv ...string) Option
  • func Headers(headers map[string]string) Option
  • func JSON(v any) Option
  • func ParamPairs(kv ...string) Option
  • func Params(params map[string]string) Option
  • func Timeout(timeout time.Duration) Option
  • func ToJSON(v any) Option
  • func ToText(v *string) Option
• type Response
  • func Delete(url string, options ...Option) (*Response, error)
  • func Get(url string, options ...Option) (*Response, error)
  • func Patch(url string, options ...Option) (*Response, error)
  • func Post(url string, options ...Option) (*Response, error)
  • func Put(url string, options ...Option) (*Response, error)
  • func (r *Response) Bytes() []byte
  • func (r *Response) Cookies() map[string]*http.Cookie
  • func (r *Response) Headers() http.Header
  • func (r *Response) JSON(v any) error
  • func (r *Response) Method() string
  • func (r *Response) StatusCode() int
  • func (r *Response) Text() string
  • func (r *Response) URL() string

Functions

func SetEnvTimeout

func SetEnvTimeout(timeout time.Duration)

SetEnvTimeout sets the default timeout for each HTTP request at the environment level.

Types

type Option

type Option func(*httpOptions)

Option is the functional option type.

func BasicAuth

func BasicAuth(username, password string) Option

BasicAuth is the option to implement HTTP Basic Auth.

func Body

func Body(body io.Reader) Option

Body sets io.Reader to hold request body.

func Data

func Data(data any) Option

Data sets raw string into the request body.

func DisableKeepAlives

func DisableKeepAlives() Option

DisableKeepAlives, if true, disables HTTP keep-alives and will only use the connection to the server for a single HTTP request.

This is unrelated to the similarly named TCP keep-alives.

func Dump

func Dump(req, resp *string) Option

Dump dumps outgoing client request and response to the corresponding input param (req or resp) if not nil.

Refer: - https://pkg.go.dev/net/http/httputil#DumpRequestOut - https://pkg.go.dev/net/http/httputil#DumpResponse

func Files

func Files(files map[string]*os.File) Option

Files sets files to a map of (field, fileHandler). It also sets the Content-Type as "multipart/form-data".

func Form

func Form(form map[string]string) Option

Form sets the given form into the request body. It also sets the Content-Type as "application/x-www-form-urlencoded".

func FormPairs

func FormPairs(kv ...string) Option

FormPairs sets form by the mapping of key, value ... Pairs panics if len(kv) is odd.

func HeaderPairs

func HeaderPairs(kv ...string) Option

HeaderPairs sets HTTP headers formed by the mapping of key, value ... Pairs panics if len(kv) is odd.

func Headers

func Headers(headers map[string]string) Option

Headers sets the HTTP headers.

func JSON

func JSON(v any) Option

JSON marshals the given struct as JSON into the request body. It also sets the Content-Type as "application/json".

func ParamPairs

func ParamPairs(kv ...string) Option

ParamPairs returns an Params formed by the mapping of key, value ... Pairs panics if len(kv) is odd.

func Params

func Params(params map[string]string) Option

Params sets the given params into the URL querystring.

func Timeout

func Timeout(timeout time.Duration) Option

Timeout specifies a time limit for requests made by this Client. The timeout includes connection time, any redirects, and reading the response body. The timer remains running after Get, Head, Post, or Do return and will interrupt reading of the Response.Body.

A Timeout of zero means no timeout. Default is 60s.

func ToJSON

func ToJSON(v any) Option

ToJSON unmarshals HTTP response body to given struct as JSON.

func ToText

func ToText(v *string) Option

ToText unmarshals HTTP response body to string.

type Response

type Response struct {
	// contains filtered or unexported fields
}

Response is a wrapper of HTTP response.

func Delete

func Delete(url string, options ...Option) (*Response, error)

Delete sends an HTTP request with DELETE method.

On error, any Response can be ignored. A non-nil Response with a non-nil error only occurs when Response.StatusCode() is not 2xx.

func Get

func Get(url string, options ...Option) (*Response, error)

Get sends an HTTP request with GET method.

On error, any Response can be ignored. A non-nil Response with a non-nil error only occurs when Response.StatusCode() is not 2xx.

func Patch

func Patch(url string, options ...Option) (*Response, error)

Patch sends an HTTP request with PATCH method.

On error, any Response can be ignored. A non-nil Response with a non-nil error only occurs when Response.StatusCode() is not 2xx.

func Post

func Post(url string, options ...Option) (*Response, error)

Post sends an HTTP POST request.

func Put

func Put(url string, options ...Option) (*Response, error)

Put sends an HTTP request with PUT method.

On error, any Response can be ignored. A non-nil Response with a non-nil error only occurs when Response.StatusCode() is not 2xx.

func (*Response) Bytes

func (r *Response) Bytes() []byte

Bytes parses the HTTP response body as []byte.

func (*Response) Cookies

func (r *Response) Cookies() map[string]*http.Cookie

Cookies parses and returns the cookies set in the Set-Cookie headers.

func (*Response) Headers

func (r *Response) Headers() http.Header

Headers maps header keys to values. If the response had multiple headers with the same key, they may be concatenated, with comma delimiters.

func (*Response) JSON

func (r *Response) JSON(v any) error

JSON decodes the HTTP response body as JSON format.

func (*Response) Method

func (r *Response) Method() string

Method returns the HTTP request method.

func (*Response) StatusCode

func (r *Response) StatusCode() int

StatusCode returns status code of HTTP response.

func (*Response) Text

func (r *Response) Text() string

Text parses the HTTP response body as string.

func (*Response) URL

func (r *Response) URL() string

URL returns the HTTP request URL string.