gorequest

package module
v0.2.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 1, 2015 License: MIT Imports: 13 Imported by: 0

README

GoRequest

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

GopherGoRequest

"Shooting Requests like a Machine Gun" - Gopher

Sending request would never been fun and easier than this. It comes with lots of feature:

  • Get/Post/Put/Head/Delete/Patch
  • Set - simple header setting
  • JSON - made it simple with JSON string as a parameter
  • 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

Drone Build Status Travis Build 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 is getting more complicated in golang. You need to create a Client, setting header in different command, ... to do just 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 making things ugly while you can just do 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 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()
JSON

For a JSON POST with standard libraries, you might need to marshal map data structure to json format, setting header to 'application/json' (and other headers if you need to) and declare http.Client. So, you code become longer and hard 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)

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("").("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()
// To unset it for any following request, just set both username and password to empty string:
request.SetBasicAuth("","")
resp, body, errs := request.Get("http://example-proxy-noauth.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.

Noted

As the underlying gorequest is based on http.Client in most usecases, 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 contributers thus far:

@kemadz, @austinov, @figlief, @dickeyxxx, @killix

Credits

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

License

GoRequest is MIT License.

Documentation

Overview

Package gorequest inspired by Nodejs SuperAgent provides easy-way to write http client

Index

Constants

View Source 
const (
	POST   = "POST"
	GET    = "GET"
	HEAD   = "HEAD"
	PUT    = "PUT"
	DELETE = "DELETE"
	PATCH  = "PATCH"
)

HTTP methods we support

Variables

View Source 
var Types = map[string]string{
	"html":       "text/html",
	"json":       "application/json",
	"xml":        "application/xml",
	"urlencoded": "application/x-www-form-urlencoded",
	"form":       "application/x-www-form-urlencoded",
	"form-data":  "application/x-www-form-urlencoded",
}

Functions

This section is empty.

Types

type Request 

type Request *http.Request

type Response 

type Response *http.Response

type SuperAgent 

type SuperAgent struct {
	Url        string
	Method     string
	Header     map[string]string
	TargetType string
	ForceType  string
	Data       map[string]interface{}
	FormData   url.Values
	QueryData  url.Values
	Client     *http.Client
	Transport  *http.Transport
	Cookies    []*http.Cookie
	Errors     []error
	BasicAuth  struct{ Username, Password string }
}

A SuperAgent is a object storing all request data for client.

func New 

func New() *SuperAgent

Used to create a new SuperAgent object.

func (*SuperAgent) AddCookie added in v0.2.2 

func (s *SuperAgent) AddCookie(c *http.Cookie) *SuperAgent

AddCookie adds a cookie to the request. The behavior is the same as AddCookie on Request from net/http

func (*SuperAgent) ClearSuperAgent 

func (s *SuperAgent) ClearSuperAgent()

Clear SuperAgent data for another new request.

func (*SuperAgent) Delete added in v0.2.0 

func (s *SuperAgent) Delete(targetUrl string) *SuperAgent

func (*SuperAgent) End 

func (s *SuperAgent) End(callback ...func(response Response, body string, errs []error)) (Response, string, []error)

End is the most important function that you need to call when ending the chain. The request won't proceed without calling it. End function returns Response which matchs the structure of Response type in Golang's http package (but without Body data). The body data itself returns as a string in a 2nd return value. Lastly but worht noticing, error array (NOTE: not just single error value) is returned as a 3rd value and nil otherwise.

For example: 

resp, body, errs := gorequest.New().Get("http://www.google.com").End()
if( errs != nil){
  fmt.Println(errs)
}
fmt.Println(resp, body)

Moreover, End function also supports callback which you can put as a parameter. This extends the flexibility and makes GoRequest fun and clean! You can use GoRequest in whatever style you love!

For example: 

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

func (*SuperAgent) Get 

func (s *SuperAgent) Get(targetUrl string) *SuperAgent

func (*SuperAgent) Head added in v0.2.0 

func (s *SuperAgent) Head(targetUrl string) *SuperAgent

func (*SuperAgent) Patch added in v0.2.3 

func (s *SuperAgent) Patch(targetUrl string) *SuperAgent

func (*SuperAgent) Post 

func (s *SuperAgent) Post(targetUrl string) *SuperAgent

func (*SuperAgent) Proxy added in v0.2.0 

func (s *SuperAgent) Proxy(proxyUrl string) *SuperAgent

Proxy function accepts a proxy url string to setup proxy url for any request. It provides a convenience way to setup proxy which have advantages over usual old ways. One example is you might try to set `http_proxy` environment. This means you are setting proxy up for all the requests. You will not be able to send different request with different proxy unless you change your `http_proxy` environment again. Another example is using Golang proxy setting. This is normal prefer way to do but too verbase compared to GoRequest's Proxy: 

gorequest.New().Proxy("http://myproxy:9999").
  Post("http://www.google.com").
  End()

To set no_proxy, just put empty string to Proxy func: 

gorequest.New().Proxy("").
  Post("http://www.google.com").
  End()

func (*SuperAgent) Put added in v0.2.0 

func (s *SuperAgent) Put(targetUrl string) *SuperAgent

func (*SuperAgent) Query 

func (s *SuperAgent) Query(content interface{}) *SuperAgent

Query function accepts either json string or strings which will form a query-string in url of GET method or body of POST method. For example, making "/search?query=bicycle&size=50x50&weight=20kg" using GET method: 

gorequest.New().
  Get("/search").
  Query(`{ query: 'bicycle' }`).
  Query(`{ size: '50x50' }`).
  Query(`{ weight: '20kg' }`).
  End()

Or you can put multiple json values: 

gorequest.New().
  Get("/search").
  Query(`{ query: 'bicycle', size: '50x50', weight: '20kg' }`).
  End()

Strings are also acceptable: 

gorequest.New().
  Get("/search").
  Query("query=bicycle&size=50x50").
  Query("weight=20kg").
  End()

Or even Mixed! :) 

gorequest.New().
  Get("/search").
  Query("query=bicycle").
  Query(`{ size: '50x50', weight:'20kg' }`).
  End()

func (*SuperAgent) RedirectPolicy 

func (s *SuperAgent) RedirectPolicy(policy func(req Request, via []Request) error) *SuperAgent

func (*SuperAgent) Send 

func (s *SuperAgent) Send(content interface{}) *SuperAgent

Send function accepts either json string or query strings which is usually used to assign data to POST or PUT method. Without specifying any type, if you give Send with json data, you are doing requesting in json format: 

gorequest.New().
  Post("/search").
  Send(`{ query: 'sushi' }`).
  End()

While if you use at least one of querystring, GoRequest understands and automatically set the Content-Type to `application/x-www-form-urlencoded` 

gorequest.New().
  Post("/search").
  Send("query=tonkatsu").
  End()

So, if you want to strictly send json format, you need to use Type func to set it as `json` (Please see more details in Type function). You can also do multiple chain of Send: 

gorequest.New().
  Post("/search").
  Send("query=bicycle&size=50x50").
  Send(`{ wheel: '4'}`).
  End()

From v0.2.0, Send function provide another convenience way to work with Struct type. You can mix and match it with json and query string: 

type BrowserVersionSupport struct {
  Chrome string
  Firefox string
}
ver := BrowserVersionSupport{ Chrome: "37.0.2041.6", Firefox: "30.0" }
gorequest.New().
  Post("/update_version").
  Send(ver).
  Send(`{"Safari":"5.1.10"}`).
  End()

func (*SuperAgent) SendString added in v0.2.0 

func (s *SuperAgent) SendString(content string) *SuperAgent

SendString returns SuperAgent's itself for any next chain and takes content string as a parameter. Its duty is to transform String into s.Data (map[string]interface{}) which later changes into appropriate format such as json, form, text, etc. in the End func. Send implicitly uses SendString and you should use Send instead of this.

func (*SuperAgent) Set 

func (s *SuperAgent) Set(param string, value string) *SuperAgent

Set is used for setting header fields. Example. To set `Accept` as `application/json` 

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

func (*SuperAgent) SetBasicAuth added in v0.2.5 

func (s *SuperAgent) SetBasicAuth(username string, password string) *SuperAgent

SetBasicAuth sets the basic authentication header Example. To set the header for username "myuser" and password "mypass" 

gorequest.New()
  Post("/gamelist").
  SetBasicAuth("myuser", "mypass").
  End()

func (*SuperAgent) TLSClientConfig added in v0.2.2 

func (s *SuperAgent) TLSClientConfig(config *tls.Config) *SuperAgent

Set TLSClientConfig for underling Transport. One example is you can use it to disable security check (https): 

gorequest.New().TLSClientConfig(&tls.Config{ InsecureSkipVerify: true}).
	Get("https://disable-security-check.com").
	End()

func (*SuperAgent) Timeout added in v0.2.0 

func (s *SuperAgent) Timeout(timeout time.Duration) *SuperAgent

func (*SuperAgent) Type 

func (s *SuperAgent) Type(typeStr string) *SuperAgent

Type is a convenience function to specify the data type to send. For example, to send data as `application/x-www-form-urlencoded` : 

gorequest.New().
  Post("/recipe").
  Type("form").
  Send(`{ name: "egg benedict", category: "brunch" }`).
  End()

This will POST the body "name=egg benedict&category=brunch" to url /recipe

GoRequest supports 

"text/html" uses "html"
"application/json" uses "json"
"application/xml" uses "xml"
"application/x-www-form-urlencoded" uses "urlencoded", "form" or "form-data"

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.