gorequest

GoRequest -- Simplified HTTP client ( inspired by nodejs SuperAgent )

3,425

415

3,425

112

View on GitHub

Top Related Projects

resty

9,906

Simple HTTP and REST client library for Go

req

4,217

Simple Go HTTP client with Black Magic

grequests

2,128

A Go "clone" of the great and famous Requests library

sling

1,672

A Go HTTP client library for creating and sending API requests

fasthttp

21,607

Fast HTTP package for Go. Tuned for high performance. Zero memory allocations in hot paths. Up to 10x faster than net/http

Quick Overview

The gorequest library is a Go HTTP client that provides a simple and expressive API for making HTTP requests. It abstracts away the low-level details of the standard Go http package, making it easier to perform common tasks such as setting headers, handling cookies, and dealing with errors.

Pros

Simplified API: The gorequest API is more concise and easier to use than the standard Go http package, making it a good choice for developers who want to write more readable and maintainable code.
Automatic Error Handling: The library automatically handles errors and provides a consistent way to check for and handle failures.
Flexible Configuration: gorequest allows you to easily configure various aspects of the HTTP request, such as headers, cookies, and query parameters.
Supports Multiple HTTP Clients: The library supports multiple HTTP client implementations, including the standard Go http client and the http.Client from the net/http package.

Cons

Dependency on Third-Party Libraries: gorequest relies on several third-party libraries, which may be a concern for some developers who prefer to use only the standard Go libraries.
Limited Documentation: The project's documentation could be more comprehensive, which may make it harder for new users to get started.
Potential Performance Overhead: The additional abstraction layer provided by gorequest may introduce a small amount of performance overhead compared to using the standard Go http package directly.
Lack of Active Maintenance: The project has not been actively maintained in recent years, which may be a concern for some users who require the latest features and bug fixes.

Code Examples

Here are a few examples of how to use the gorequest library:

// Making a simple GET request
resp, body, errs := gorequest.New().Get("https://example.com").End()
if len(errs) > 0 {
    // Handle errors
}
fmt.Println(resp.Status)
fmt.Println(body)

// Setting headers and query parameters
resp, body, errs := gorequest.New().
    Get("https://example.com/api").
    Set("Authorization", "Bearer token").
    Query("limit=10").
    Query("offset=20").
    End()
if len(errs) > 0 {
    // Handle errors
}
fmt.Println(resp.Status)
fmt.Println(body)

// Sending a POST request with a JSON payload
payload := map[string]interface{}{
    "name": "John Doe",
    "email": "john.doe@example.com",
}
resp, body, errs := gorequest.New().
    Post("https://example.com/api/users").
    SendStruct(payload).
    End()
if len(errs) > 0 {
    // Handle errors
}
fmt.Println(resp.Status)
fmt.Println(body)

Getting Started

To get started with the gorequest library, you can install it using the Go package manager:

go get -u github.com/parnurzeal/gorequest

Once you have the library installed, you can start using it in your Go code. Here's a simple example that demonstrates how to make a GET request:

package main

import (
    "fmt"
    "github.com/parnurzeal/gorequest"
)

func main() {
    resp, body, errs := gorequest.New().Get("https://example.com").End()
    if len(errs) > 0 {
        fmt.Println("Error:", errs)
        return
    }
    fmt.Println("Status:", resp.Status)
    fmt.Println("Body:", body)
}

This code creates a new gorequest instance, makes a GET request to https://example.com, and prints the response status and body. You can customize the request by setting headers, query parameters, and request bodies as needed.

Competitor Comparisons

resty

9,906

Simple HTTP and REST client library for Go

Pros of resty

More actively maintained with frequent updates and bug fixes
Comprehensive feature set, including support for HTTP/2 and advanced authentication methods
Better performance and memory efficiency

Cons of resty

Steeper learning curve due to more extensive API
May be considered "overkill" for simple use cases

Code Comparison

gorequest:

resp, body, errs := gorequest.New().Get("http://example.com").End()

resty:

resp, err := resty.New().R().Get("http://example.com")
body := resp.Body()

Key Differences

resty provides a more idiomatic Go experience with its error handling approach
gorequest uses a chainable API, while resty uses a more traditional method-based approach
resty offers more fine-grained control over request and response handling

Use Cases

gorequest: Quick and simple HTTP requests with minimal setup
resty: Complex API integrations, projects requiring advanced HTTP features, or performance-critical applications

Community and Ecosystem

resty has a larger and more active community, resulting in better documentation and third-party integrations
gorequest has a smaller but loyal user base, particularly for simpler use cases

Both libraries serve their purposes well, but resty is generally considered more robust and feature-rich, making it a better choice for larger or more complex projects.

req

4,217

Simple Go HTTP client with Black Magic

Pros of req

More actively maintained with recent updates
Better performance and lower memory usage
Supports HTTP/2 and more modern features

Cons of req

Less established community and ecosystem
Fewer third-party extensions and plugins
Steeper learning curve for beginners

Code Comparison

req:

client := req.C().EnableDebugLog()
resp, err := client.R().
    SetHeader("Content-Type", "application/json").
    SetBody(map[string]string{"key": "value"}).
    Post("https://api.example.com/endpoint")

gorequest:

resp, body, errs := gorequest.New().
    Post("https://api.example.com/endpoint").
    Set("Content-Type", "application/json").
    Send(map[string]string{"key": "value"}).
    End()

Both libraries provide a fluent interface for making HTTP requests, but req offers more modern features and better performance. gorequest has a simpler API that may be easier for beginners to understand. req's approach to creating a client and then making requests allows for more flexibility and reusability, while gorequest's chaining method is more concise for simple use cases.

grequests

2,128

A Go "clone" of the great and famous Requests library

Pros of grequests

More actively maintained with recent updates
Better support for modern Go features and idioms
Simpler API with fewer dependencies

Cons of grequests

Less extensive feature set compared to gorequest
Fewer built-in convenience methods for common tasks
Less flexibility in customizing request behavior

Code Comparison

grequests:

resp, err := grequests.Get("http://example.com", nil)
if err != nil {
    log.Fatalln("Unable to make request: ", err)
}

gorequest:

resp, body, errs := gorequest.New().Get("http://example.com").End()
if len(errs) > 0 {
    log.Fatalln("Unable to make request: ", errs)
}

Both libraries aim to simplify HTTP requests in Go, but they take different approaches. grequests focuses on a more straightforward API with fewer bells and whistles, while gorequest offers a more feature-rich experience at the cost of a slightly more complex API.

grequests is better suited for developers who prefer a minimalist approach and want to leverage modern Go features. On the other hand, gorequest might be more appealing to those who need a wide range of built-in functionalities and don't mind a slightly steeper learning curve.

Ultimately, the choice between the two libraries depends on the specific requirements of your project and your personal coding preferences.

sling

1,672

A Go HTTP client library for creating and sending API requests

Pros of sling

More lightweight and focused on core HTTP functionality
Better type safety with strongly typed request and response methods
Easier to test due to its modular design and use of interfaces

Cons of sling

Less feature-rich compared to gorequest's extensive functionality
Steeper learning curve for beginners due to its more low-level approach
Lacks built-in support for some advanced features like multipart file uploads

Code comparison

sling:

req, _ := sling.New().Get("https://api.example.com").Request()
resp, err := http.DefaultClient.Do(req)

gorequest:

resp, body, errs := gorequest.New().Get("https://api.example.com").End()

Summary

sling is a more lightweight and type-safe HTTP client library, focusing on core functionality and modularity. It offers better testability but may require more setup for advanced features. gorequest provides a more feature-rich and user-friendly experience out of the box, with simpler syntax for common operations. The choice between the two depends on the specific needs of the project and the developer's preference for either a more low-level, flexible approach (sling) or a higher-level, convenience-oriented solution (gorequest).

fasthttp

21,607

Fast HTTP package for Go. Tuned for high performance. Zero memory allocations in hot paths. Up to 10x faster than net/http

Pros of fasthttp

Significantly faster performance and lower memory usage
Optimized for high-concurrency scenarios
Provides both client and server implementations

Cons of fasthttp

Less feature-rich and user-friendly API compared to gorequest
Not fully compatible with net/http, requiring some code changes
Lacks built-in support for some common features like cookies and redirects

Code Comparison

gorequest:

resp, body, errs := gorequest.New().
    Get("http://example.com").
    End()

fasthttp:

req := fasthttp.AcquireRequest()
resp := fasthttp.AcquireResponse()
fasthttp.Do(req, resp)
body := resp.Body()

Summary

fasthttp is designed for high-performance scenarios, offering significant speed improvements over standard net/http and gorequest. However, it sacrifices some ease of use and compatibility for this performance gain. gorequest provides a more user-friendly API with built-in features like method chaining and automatic handling of common tasks, making it easier to use for simple HTTP requests. The choice between the two depends on whether raw performance or developer convenience is the primary concern for the project at hand.

heimdall

2,613

An enhanced HTTP client for Go

Pros of Heimdall

Built-in circuit breaker functionality for improved fault tolerance
Supports multiple retry mechanisms and backoff strategies
Offers more advanced features like hystrix-like circuit breaking

Cons of Heimdall

Less intuitive API compared to GoRequest's chainable methods
Requires more setup and configuration for basic use cases
Lacks some convenience methods for common HTTP operations

Code Comparison

GoRequest:

resp, body, errs := gorequest.New().
    Get("http://example.com").
    End()

Heimdall:

client := heimdall.NewHTTPClient(timeout)
res, err := client.Get("http://example.com", nil)
body, err := ioutil.ReadAll(res.Body)

Summary

Heimdall offers more advanced features for building resilient HTTP clients, including circuit breaking and flexible retry mechanisms. However, it comes with a steeper learning curve and requires more setup compared to GoRequest's simpler, more intuitive API. GoRequest provides a more straightforward approach for basic HTTP operations, while Heimdall is better suited for complex scenarios requiring fault tolerance and advanced error handling.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

GoRequest

GoRequest -- Simplified HTTP client ( inspired by famous SuperAgent lib in Node.js )

GopherGoRequest

"Shooting Requests like a Machine Gun" - Gopher

Sending request has never been as fun nor easier than this. It comes with lots of features:

Get/Post/Put/Head/Delete/Patch/Options
Set - simple header setting
JSON - made it simple with JSON string as a parameter
Multipart-Support - send data and files as multipart request
Proxy - sending request via proxy
Timeout - setting timeout for a request
TLSClientConfig - taking control over tls where at least you can disable security check for https
RedirectPolicy
Cookie - setting cookies for your request
CookieJar - automatic in-memory cookiejar
BasicAuth - setting basic authentication header
more to come..

Installation

$ go get github.com/parnurzeal/gorequest

Documentation

See Go Doc or Go Walker for usage and details.

Status

Why should you use GoRequest?

GoRequest makes thing much more simple for you, making http client more awesome and fun like SuperAgent + golang style usage.

This is what you normally do for a simple GET without GoRequest:

resp, err := http.Get("http://example.com/")

With GoRequest:

request := gorequest.New()
resp, body, errs := request.Get("http://example.com/").End()

Or below if you don't want to reuse it for other requests.

resp, body, errs := gorequest.New().Get("http://example.com/").End()

How about getting control over HTTP client headers, redirect policy, and etc. Things can quickly get more complicated in golang. You need to create a Client, set headers in a different command, ... just to do only one GET

client := &http.Client{
  CheckRedirect: redirectPolicyFunc,
}

req, err := http.NewRequest("GET", "http://example.com", nil)

req.Header.Add("If-None-Match", `W/"wyzzy"`)
resp, err := client.Do(req)

Why make things ugly while you can just do it as follows:

request := gorequest.New()
resp, body, errs := request.Get("http://example.com").
  RedirectPolicy(redirectPolicyFunc).
  Set("If-None-Match", `W/"wyzzy"`).
  End()

DELETE, HEAD, POST, PUT, PATCH are now supported and can be used in the same way as GET:

request := gorequest.New()
resp, body, errs := request.Post("http://example.com").End()
// PUT -> request.Put("http://example.com").End()
// DELETE -> request.Delete("http://example.com").End()
// HEAD -> request.Head("http://example.com").End()
// ANYTHING -> request.CustomMethod("TRACE", "http://example.com").End()

JSON

For a JSON POST with standard libraries, you might need to marshal map data structure to json format, set headers to 'application/json' (and other headers if you need to) and declare http.Client. So, your code becomes longer and harder to maintain:

m := map[string]interface{}{
  "name": "backy",
  "species": "dog",
}
mJson, _ := json.Marshal(m)
contentReader := bytes.NewReader(mJson)
req, _ := http.NewRequest("POST", "http://example.com", contentReader)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Notes","GoRequest is coming!")
client := &http.Client{}
resp, _ := client.Do(req)

Compared to our GoRequest version, JSON is for sure a default. So, it turns out to be just one simple line!:

request := gorequest.New()
resp, body, errs := request.Post("http://example.com").
  Set("Notes","gorequst is coming!").
  Send(`{"name":"backy", "species":"dog"}`).
  End()

Moreover, it also supports struct type. So, you can have a fun Mix & Match sending the different data types for your request:

type BrowserVersionSupport struct {
  Chrome string
  Firefox string
}
ver := BrowserVersionSupport{ Chrome: "37.0.2041.6", Firefox: "30.0" }
request := gorequest.New()
resp, body, errs := request.Post("http://version.com/update").
  Send(ver).
  Send(`{"Safari":"5.1.10"}`).
  End()

Not only for Send() but Query() is also supported. Just give it a try! :)

Callback

Moreover, GoRequest also supports callback function. This gives you much more flexibility on using it. You can use it any way to match your own style! Let's see a bit of callback example:

func printStatus(resp gorequest.Response, body string, errs []error){
  fmt.Println(resp.Status)
}
gorequest.New().Get("http://example.com").End(printStatus)

Multipart/Form-Data

You can specify the content-type of the request to type multipart to send all data as multipart/form-data. This feature also allows you to send (multiple) files! Check the examples below!

gorequest.New().Post("http://example.com/").
  Type("multipart").
  Send(`{"query1":"test"}`).
  End()

The SendFile function accepts strings as path to a file, []byte slice or even a os.File! You can also combine them to send multiple files with either custom name and/or custom fieldname:

          f, _ := filepath.Abs("./file2.txt")
bytesOfFile, _ := ioutil.ReadFile(f)

gorequest.New().Post("http://example.com/").
  Type("multipart").
  SendFile("./file1.txt").
  SendFile(bytesOfFile, "file2.txt", "my_file_fieldname").
  End()

Check the docs for SendFile to get more information about the types of arguments.

Headers

When setting one header to the request, the Set method can be used:

gorequest.New().
      Post("/gamelist").
      Set("Accept", "application/json").
      End()

This will clear all headers currently attached to a request and add the specified header.

If there are multiple headers that must be appended to the request before sending, use AppendHeader. These can be chained together to add additional headers to the request:

gorequest.New().
      Post("/gamelist").
      AppendHeader("Accept", "application/json").
      AppendHeader("Accept", "text/plain").
      End()

See the docs for the Set and AppendHeader methods for information about parameter and return types.

Proxy

In the case when you are behind proxy, GoRequest can handle it easily with Proxy func:

request := gorequest.New().Proxy("http://proxy:999")
resp, body, errs := request.Get("http://example-proxy.com").End()
// To reuse same client with no_proxy, use empty string:
resp, body, errs = request.Proxy("").Get("http://example-no-proxy.com").End()

Basic Authentication

To add a basic authentication header:

request := gorequest.New().SetBasicAuth("username", "password")
resp, body, errs := request.Get("http://example-proxy.com").End()

Timeout

Timeout can be set in any time duration using time package:

request := gorequest.New().Timeout(2*time.Millisecond)
resp, body, errs:= request.Get("http://example.com").End()

Timeout func defines both dial + read/write timeout to the specified time parameter.

EndBytes

Thanks to @jaytaylor, we now have EndBytes to use when you want the body as bytes.

The callbacks work the same way as with End, except that a byte array is used instead of a string.

resp, bodyBytes, errs := gorequest.New().Get("http://example.com/").EndBytes()

EndStruct

We now have EndStruct to use when you want the body as struct.

The callbacks work the same way as with End, except that a struct is used instead of a string.

Supposing the URL http://example.com/ returns the body {"hey":"you"}

heyYou struct {
  Hey string `json:"hey"`
}

var heyYou heyYou

resp, _, errs := gorequest.New().Get("http://example.com/").EndStruct(&heyYou)

Retry

Supposing you need retry 3 times, with 5 seconds between each attempt when gets a BadRequest or a InternalServerError

request := gorequest.New()
resp, body, errs := request.Get("http://example.com/").
                    Retry(3, 5 * time.Second, http.StatusBadRequest, http.StatusInternalServerError).
                    End()

Handling Redirects

Redirects can be handled with RedirectPolicy which behaves similarly to net/http Client's CheckRedirect function. Simply specify a function which takes the Request about to be made and a slice of previous Requests in order of oldest first. When this function returns an error, the Request is not made.

For example to redirect only to https endpoints:

request := gorequest.New()
resp, body, errs := request.Get("http://example.com/").
                    RedirectPolicy(func(req Request, via []*Request) error {
                      if req.URL.Scheme != "https" {
                        return http.ErrUseLastResponse
                      }
                    }).
                    End()

Clone

You can reuse settings of a Request by cloning it before making any requests. This can be useful if you wish to re-use the SuperAgent across multiple requests without worrying about concurrency or having too many Transports being created.

Clones will copy the same settings (headers, query, etc..), but will only shallow copy any "Data" given to it. They will also share the same Transport and http.Client.

baseRequest := gorequest.New()
// apply anything you want to these settings. Eg:
baseRequest.Timeout(10 * time.Millisecond).
  BasicAuth("user", "password")

// then reuse the base request elsewhere, cloning before modifying or using it.
resp, body, errs := baseRequest.Clone().Get("http://exmaple.com/").End()

Debug

For debugging, GoRequest leverages httputil to dump details of every request/response. (Thanks to @dafang)

You can just use SetDebug or environment variable GOREQUEST_DEBUG=0|1 to enable/disable debug mode and SetLogger to set your own choice of logger.

Thanks to @QuentinPerez, we can see even how gorequest is compared to CURL by using SetCurlCommand.

Noted

As the underlying gorequest is based on http.Client in most use cases, gorequest.New() should be called once and reuse gorequest as much as possible.

Contributing to GoRequest:

If you find any improvement or issue you want to fix, feel free to send me a pull request with testing.

Thanks to all contributors thus far:

Contributors
https://github.com/alaingilbert
https://github.com/austinov
https://github.com/coderhaoxin
https://github.com/codegoalie
https://github.com/dafang
https://github.com/davyzhang
https://github.com/dickeyxxx
https://github.com/figlief
https://github.com/fraenky8
https://github.com/franciscocpg
https://github.com/heytitle
https://github.com/hownowstephen
https://github.com/kemadz
https://github.com/killix
https://github.com/jaytaylor
https://github.com/na-ga
https://github.com/piotrmiskiewicz
https://github.com/pencil001
https://github.com/pkopac
https://github.com/quangbuule
https://github.com/QuentinPerez
https://github.com/smallnest
https://github.com/WaveCutz
https://github.com/xild
https://github.com/yangmls
https://github.com/6david9

Also, co-maintainer is needed here. If anyone is interested, please email me (parnurzeal at gmail.com)

Credits

Renee French - the creator of Gopher mascot
Wisi Mongkhonsrisawat for providing an awesome GoRequest's Gopher image :)

License

GoRequest is MIT License.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot