GoReq

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?
  • Making requests with different methods
  • GET
    • Tags
  • POST
    • Sending payloads in the Body
  • Specifiying request headers
  • Sending Cookies
  • Setting timeouts
• Using the Response and Error
• Receiving JSON
• Sending/Receiving Compressed Payloads
  • Using gzip compression:
  • Using deflate compression:
  • Using compressed responses:
• Proxy
• Debugging requests
  • Getting raw Request & Response
• TODO:

Why GoReq?

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.

How do I install it?

go get github.com/franela/goreq

What can I do with it?

Making requests with different methods

GET

res, err := goreq.Request{ Uri: "http://www.google.com" }.Do()

GoReq default method is GET.

You can also set value to GET method easily

type Item struct {
        Limit int
        Skip int
        Fields string
}

item := Item {
        Limit: 3,
        Skip: 5,
        Fields: "Value",
}

res, err := goreq.Request{
        Uri: "http://localhost:3000/",
        QueryString: item,
}.Do()

The sample above will send http://localhost:3000/?limit=3&skip=5&fields=Value

Alternatively the url tag can be used in struct fields to customize encoding properties

type Item struct {
        TheLimit int `url:"the_limit"`
        TheSkip string `url:"the_skip,omitempty"`
        TheFields string `url:"-"`
}

item := Item {
        TheLimit: 3,
        TheSkip: "",
        TheFields: "Value",
}

res, err := goreq.Request{
        Uri: "http://localhost:3000/",
        QueryString: item,
}.Do()

The sample above will send http://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")

res, err := goreq.Request{
        Uri: "http://localhost:3000/",
        QueryString: item,
}.Do()

The sample above will send http://localhost:3000/?limit=3&field=somefield&field=someotherfield

Tags

Struct field url 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 this
  • squash: the fields of embedded struct is used for parameter

Tag Examples

type Place struct {
    Country string `url:"country"`
    City    string `url:"city"`
    ZipCode string `url:"zipcode,omitempty"`
}

type Person struct {
    Place `url:",squash"`

    FirstName string `url:"first_name"`
    LastName  string `url:"last_name"`
    Age       string `url:"age,omitempty"`
    Password  string `url:"-"`
}

johnbull := Person{
	Place: Place{ // squash the embedded struct value
		Country: "UK",
		City:    "London",
		ZipCode: "SW1",
	},
	FirstName: "John",
	LastName:  "Doe",
	Age:       "35",
	Password:  "my-secret", // ignored for parameter
}

goreq.Request{
	Uri:         "http://localhost/",
	QueryString: johnbull,
}.Do()
// =>  `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 value
		Country: "Japan",
		City:    "Tokyo",
	},
	LastName: "Yagyu",
}

goreq.Request{
	Uri:         "http://localhost/",
	QueryString: samurai,
}.Do()
// =>  `http://localhost/?first_name=&last_name=yagyu&country=Japan&city=Tokyo`

POST

res, err := goreq.Request{ Method: "POST", Uri: "http://www.google.com" }.Do()

Sending payloads in the Body

You can send string, Reader or interface{} in the body. The first two will be sent as text. The last one will be marshalled to JSON, if possible.

type Item struct {
    Id int
    Name string
}

item := Item{ Id: 1111, Name: "foobar" }

res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
}.Do()

Specifiying request headers

We think that most of the times the request headers that you use are: Host, Content-Type, Accept and User-Agent. This is why we decided to make it very easy to set these headers.

res, err := goreq.Request{
    Uri: "http://www.google.com",
    Host: "foobar.com",
    Accept: "application/json",
    ContentType: "application/json",
    UserAgent: "goreq",
}.Do()

But sometimes you need to set other headers. You can still do it.

req := goreq.Request{ Uri: "http://www.google.com" }

req.AddHeader("X-Custom", "somevalue")

req.Do()

Alternatively you can use the WithHeader function to keep the syntax short

res, err = goreq.Request{ Uri: "http://www.google.com" }.WithHeader("X-Custom", "somevalue").Do()

Cookie support

Cookies can be either set at the request level by sending a CookieJar in the CookieJar request field or you can use goreq's one-liner WithCookie method as shown below

res, err := goreq.Request{
    Uri: "http://www.google.com",
}.
WithCookie(&http.Cookie{Name: "c1", Value: "v1"}).
Do()

Setting timeouts

GoReq supports 2 kind of timeouts. A general connection timeout and a request specific one. By default the connection timeout is of 1 second. There is no default for request timeout, which means it will wait forever.

You can change the connection timeout doing:

goreq.SetConnectTimeout(100 * time.Millisecond)

And specify the request timeout doing:

res, err := goreq.Request{
    Uri: "http://www.google.com",
    Timeout: 500 * time.Millisecond,
}.Do()

Using the Response and Error

GoReq will always return 2 values: a Response and an Error. If Error is not nil it means that an error happened while doing the request and you shouldn't use the Response 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:

if serr, ok := err.(*goreq.Error); ok {
    if serr.Timeout() {
        ...
    }
}
return err

If you don't get an error, you can safely use the Response.

res.Uri // return final URL location of the response (fulfilled after redirect was made)
res.StatusCode // return the status code of the response
res.Body // gives you access to the body
res.Body.ToString() // will return the body as a string
res.Header.Get("Content-Type") // gives you access to all the response headers

Remember that you should always close res.Body if it's not nil

Receiving JSON

GoReq will help you to receive and unmarshal JSON.

type Item struct {
    Id int
    Name string
}

var item Item

res.Body.FromJsonTo(&item)

Sending/Receiving Compressed Payloads

GoReq supports gzip, deflate and zlib compression of requests' body and transparent decompression of responses provided they have a correct Content-Encoding header.

Using gzip compression:

res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
    Compression: goreq.Gzip(),
}.Do()

Using deflate/zlib compression:

res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
    Compression: goreq.Deflate(),
}.Do()

Using compressed responses:

If servers replies a correct and matching Content-Encoding header (gzip requires Content-Encoding: gzip and deflate Content-Encoding: deflate) goreq transparently decompresses the response so the previous example should always work:

type Item struct {
    Id int
    Name string
}
res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
    Compression: goreq.Gzip(),
}.Do()
var item Item
res.Body.FromJsonTo(&item)

If no Content-Encoding header is replied by the server GoReq will return the crude response.

Proxy

If you need to use a proxy for your requests GoReq supports the standard http_proxy env variable as well as manually setting the proxy for each request

res, err := goreq.Request{
    Method: "GET",
    Proxy: "http://myproxy:myproxyport",
    Uri: "http://www.google.com",
}.Do()

Proxy basic auth is also supported

res, err := goreq.Request{
    Method: "GET",
    Proxy: "http://user:pass@myproxy:myproxyport",
    Uri: "http://www.google.com",
}.Do()

Debug

If you need to debug your http requests, it can print the http request detail.

res, err := goreq.Request{
	Method:      "GET",
	Uri:         "http://www.google.com",
	Compression: goreq.Gzip(),
	ShowDebug:   true,
}.Do()
fmt.Println(res, err)

and it will print the log:

GET / HTTP/1.1
Host: www.google.com
Accept:
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type:

Getting raw Request & Response

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 else
request, _ := req.NewRequest()

To get the Response:

res, err := goreq.Request{
	Method:      "GET",
	Uri:         "http://www.google.com",
	Compression: goreq.Gzip(),
	ShowDebug:   true,
}.Do()

// res.Response will contain the original http.Response structure 
fmt.Println(res.Response, err)

TODO:

We do have a couple of issues pending we'll be addressing soon. But feel free to contribute and send us PRs (with tests please 😄).