- Notifications
You must be signed in to change notification settings - Fork11
Minimal and simple request library for Go language
License
globocom/goreq
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Simple and sane HTTP request library for Go language.
Table of Contents
- Why GoReq?
- How do I install it?
- What can I do with it?
- Using the Response and Error
- Receiving JSON
- Sending/Receiving Compressed Payloads
- Proxy
- Debugging requests
- TODO:
Go has very nice native libraries that allows you to do lots of cool things. But sometimes those libraries are too low level, which means that to do a simple thing, like an HTTP Request, it takes some time. And if you want to do something as simple as adding a timeout to a request, you will end up writing several lines of code.
This is why we think GoReq is useful. Because you can do all your HTTP requests in a very simple and comprehensive way, while enabling you to do more advanced stuff by giving you access to the native API.
go get github.com/globocom/goreq
options:=Options{Insecure:true,Timeout:time.Duration(20*time.Second),}client:=NewClient(options)
You can create a client with the following configuration options:
typeOptionsstruct {Timeout time.Duration// Timeout specifies a time for request made by this clientInsecurebool// Insecure specifiesMaxRedirectsint// MaxRedirect specifies a limit redirects for policy redirectCookieJar http.CookieJar// CookieJar specifies a jar used for insert cookiesProxystring// Proxy specifies an url proxyProxyConnectHeaders http.Header// ProxyConnectHeaders specifies a header's proxyMaxIdleConnsPerHostint// MaxIdleConnsPerHost specifies a limit connections to keep per-host}
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://www.google.com" }res,err:=client.Do(req)
GoReq default method is GET.
You can also set value to GET method easily
typeItemstruct {LimitintSkipintFieldsstring}item:=Item {Limit:3,Skip:5,Fields:"Value",}client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://localhost:3000/",QueryString:item,}res,err:=client.Do(req)
The sample above will sendhttp://localhost:3000/?limit=3&skip=5&fields=Value
Alternatively theurl tag can be used in struct fields to customize encoding properties
typeItemstruct {TheLimitint`url:"the_limit"`TheSkipstring`url:"the_skip,omitempty"`TheFieldsstring`url:"-"`}item:=Item {TheLimit:3,TheSkip:"",TheFields:"Value",}client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://localhost:3000/",QueryString:item,}res,err:=client.Do(req)
The sample above will sendhttp://localhost:3000/?the_limit=3
QueryString also support url.Values
item:= url.Values{}item.Set("Limit",3)item.Add("Field","somefield")item.Add("Field","someotherfield")client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://localhost:3000/",QueryString:item,}res,err:=client.Do(req)
The sample above will sendhttp://localhost:3000/?limit=3&field=somefield&field=someotherfield
Struct fieldurl tag is mainly used as the request parameter name.Tags can be comma separated multiple values, 1st value is for naming and rest has special meanings.
special tag for 1st value
-: value is ignored if set this
special tag for rest 2nd value
omitempty: zero-value is ignored if set thissquash: the fields of embedded struct is used for parameter
typePlacestruct {Countrystring`url:"country"`Citystring`url:"city"`ZipCodestring`url:"zipcode,omitempty"`}typePersonstruct {Place`url:",squash"`FirstNamestring`url:"first_name"`LastNamestring`url:"last_name"`Agestring`url:"age,omitempty"`Passwordstring`url:"-"`}johnbull:=Person{Place:Place{// squash the embedded struct valueCountry:"UK",City:"London",ZipCode:"SW1",},FirstName:"John",LastName:"Doe",Age:"35",Password:"my-secret",// ignored for parameter}client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://localhost/",QueryString:johnbull,}res,err:=client.Do(req)// => `http://localhost/?first_name=John&last_name=Doe&age=35&country=UK&city=London&zip_code=SW1`// age and zipcode will be ignored because of `omitempty`// but firstname isn't.samurai:=Person{Place:Place{// squash the embedded struct valueCountry:"Japan",City:"Tokyo",},LastName:"Yagyu",}client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://localhost/",QueryString:samurai,}res,err:=client.Do(req)// => `http://localhost/?first_name=&last_name=yagyu&country=Japan&city=Tokyo`
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Method:"POST",Uri:"http://www.google.com" }res,err:=client.Do(req)
You can sendstring,Reader orinterface{} in the body. The first two will be sent as text. The last one will be marshalled to JSON, if possible.
typeItemstruct {IdintNamestring}item:=Item{Id:1111,Name:"foobar" }client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Method:"POST",Uri:"http://www.google.com",Body:item,}res,err:=client.Do(req)
We think that most of the times the request headers that you use are:Host,Content-Type,Accept andUser-Agent. This is why we decided to make it very easy to set these headers.
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://www.google.com",Host:"foobar.com",Accept:"application/json",ContentType:"application/json",UserAgent:"goreq",}res,err:=client.Do(req)
But sometimes you need to set other headers. You can still do it.
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://www.google.com" }req.AddHeader("X-Custom","somevalue")res,err:=client.Do(req)
Cookies can be either set at the request level by sending aCookieJar in theCookieJar request fieldor you can use goreq's one-liner AddCookie method as shown below
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Uri:"http://www.google.com",}req.AddCookie(&http.Cookie{Name:"c1",Value:"v1"})res,err:=client.Do(req)
GoReq will always return 2 values: aResponse and anError.IfError is notnil it means that an error happened while doing the request and you shouldn't use theResponse in any way.You can check what happened by getting the error message:
fmt.Println(err.Error())
And to make it easy to know if it was a timeout error, you can ask the error or return it:
ifserr,ok:=err.(*goreq.Error);ok {ifserr.Timeout() {... }}returnerr
If you don't get an error, you can safely use theResponse.
res.Uri// return final URL location of the response (fulfilled after redirect was made)res.StatusCode// return the status code of the responseres.Body// gives you access to the bodyres.Body.ToString()// will return the body as a stringres.Header.Get("Content-Type")// gives you access to all the response headers
Remember that you shouldalways closeres.Body if it's notnil
GoReq will help you to receive and unmarshal JSON.
typeItemstruct {IdintNamestring}varitemItemres.Body.FromJsonTo(&item)
GoReq supports gzip, deflate and zlib compression of requests' body and transparent decompression of responses provided they have a correctContent-Encoding header.
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Method:"POST",Uri:"http://www.google.com",Body:item,Compression:goreq.Gzip(),}res,err:=client.Do(req)
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Method:"POST",Uri:"http://www.google.com",Body:item,Compression:goreq.Deflate(),}res,err:=client.Do(req)
If servers replies a correct and matchingContent-Encoding header (gzip requiresContent-Encoding: gzip and deflateContent-Encoding: deflate) goreq transparently decompresses the response so the previous example should always work:
typeItemstruct {IdintNamestring}client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Method:"POST",Uri:"http://www.google.com",Body:item,Compression:goreq.Gzip(),}res,err:=client.Do(req)varitemItemres.Body.FromJsonTo(&item)
If noContent-Encoding header is replied by the server GoReq will return the crude response.
If you need to use a proxy for your requests GoReq supports the standardhttp_proxy env variable as well as manually setting the proxy for each request
client:=goreq.NewClient(goreq.Options{Proxy:"http://myproxy:myproxyport",})req:= goreq.Request{Method:"GET",Uri:"http://www.google.com",}res,err:=client.Do(req)
client:=goreq.NewClient(goreq.Options{Proxy:"http://user:pass@myproxy:myproxyport",})req:= goreq.Request{Method:"GET",Uri:"http://www.google.com",}res,err:=client.Do(req)
If you need to debug your http requests, it can print the http request detail.
client:=goreq.NewClient(goreq.Options{})req:= goreq.Request{Method:"GET",Uri:"http://www.google.com",Compression:goreq.Gzip(),ShowDebug:true,}res,err:=client.Do(req)fmt.Println(res,err)
and it will print the log:
GET / HTTP/1.1Host: www.google.comAccept:Accept-Encoding: gzipContent-Encoding: gzipContent-Type:To get the Request:
req:= goreq.Request{Host:"foobar.com",}//req.Request will return a new instance of an http.Request so you can safely use it for something elserequest,_:=req.NewRequest()
To get the Response:
client:=goreq.NewClient(goreq.Options{})res,err:= goreq.Request{Method:"GET",Uri:"http://www.google.com",Compression:goreq.Gzip(),ShowDebug:true,}res,err:=client.Do(req)// res.Response will contain the original http.Response structurefmt.Println(res.Response,err)
We do have a couple ofissues pending we'll be addressing soon. But feel free tocontribute and send us PRs (with tests please 😄).
About
Minimal and simple request library for Go language
Resources
License
Stars
Watchers
Forks
Packages0
Languages
- Go99.9%
- Makefile0.1%