Resty
Simple HTTP and REST client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)
Resty Communication Channels
![Twitter @go_resty](https://img.shields.io/badge/twitter-@go__resty-55acee.svg)
News
- v2.14.0 released and tagged on Aug 04, 2024.
- v2.0.0 released and tagged on Jul 16, 2019.
- v1.12.0 released and tagged on Feb 27, 2019.
- v1.0 released and tagged on Sep 25, 2017. - Resty's first version was released on Sep 15, 2015 then it grew gradually as a very handy and helpful library. Its been a two years since first release. I'm very thankful to Resty users and its contributors.
Features
- GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS, etc.
- Simple and chainable methods for settings and request
- Request Body can be
string
, []byte
, struct
, map
, slice
and io.Reader
too
- Auto detects
Content-Type
- Buffer less processing for
io.Reader
- Native
*http.Request
instance may be accessed during middleware and request execution via Request.RawRequest
- Request Body can be read multiple times via
Request.RawRequest.GetBody()
- Response object gives you more possibility
- Access as
[]byte
array - response.Body()
OR Access as string
- response.String()
- Know your
response.Time()
and when we response.ReceivedAt()
- Automatic marshal and unmarshal for
JSON
and XML
content type
- Easy to upload one or more file(s) via
multipart/form-data
- Auto detects file content type
- Request URL Path Params (aka URI Params)
- Backoff Retry Mechanism with retry condition function reference
- Resty client HTTP & REST Request and Response middlewares
Request.SetContext
supported- Authorization option of
BasicAuth
and Bearer
token - Set request
ContentLength
value for all request or particular request - Custom Root Certificates and Client Certificates
- Download/Save HTTP response directly into File, like
curl -o
flag. See SetOutputDirectory & SetOutput. - Cookies for your request and CookieJar support
- SRV Record based request instead of Host URL
- Client settings like
Timeout
, RedirectPolicy
, Proxy
, TLSClientConfig
, Transport
, etc. - Optionally allows GET request with payload, see SetAllowGetMethodPayload
- Supports registering external JSON library into resty, see how to use
- Exposes Response reader without reading response (no auto-unmarshaling) if need be, see how to use
- Option to specify expected
Content-Type
when response Content-Type
header missing. Refer to #92 - Resty design
- Have client level settings & options and also override at Request level if you want to
- Request and Response middleware
- Create Multiple clients if you want to
resty.New()
- Supports
http.RoundTripper
implementation, see SetTransport - goroutine concurrent safe
- Resty Client trace, see Client.EnableTrace and Request.EnableTrace
- Since v2.4.0, trace info contains a
RequestAttempt
value, and the Request
object contains an Attempt
attribute
- Debug mode - clean and informative logging presentation
- Gzip - Go does it automatically also resty has fallback handling too
- Works fine with
HTTP/2
and HTTP/1.1
- Bazel support
- Easily mock Resty for testing, for e.g.
- Well tested client library
Included Batteries
- Redirect Policies - see how to use
- NoRedirectPolicy
- FlexibleRedirectPolicy
- DomainCheckRedirectPolicy
- etc. more info
- Retry Mechanism how to use
- Backoff Retry
- Conditional Retry
- Since v2.6.0, Retry Hooks - Client, Request
- SRV Record based request instead of Host URL how to use
- etc (upcoming - throw your idea's here).
Supported Go Versions
Recommended to use go1.16
and above.
Initially Resty started supporting go modules
since v1.10.0
release.
Starting Resty v2 and higher versions, it fully embraces go modules package release. It requires a Go version capable of understanding /vN
suffixed imports:
It might be beneficial for your project :smile:
Resty author also published following projects for Go Community.
- aah framework - A secure, flexible, rapid Go web framework.
- THUMBAI - Go Mod Repository, Go Vanity Service and Simple Proxy Server.
- go-model - Robust & Easy to use model mapper and utility methods for Go
struct
.
Installation
require github.com/go-resty/resty/v2 v2.11.0
Usage
The following samples will assist you to become as comfortable as possible with resty library.
import "github.com/go-resty/resty/v2"
Simple GET
client := resty.New()
resp, err := client.R().
EnableTrace().
Get("https://httpbin.org/get")
curlCmdExecuted := resp.Request.GenerateCurlCommand()
fmt.Println("Curl Command:\n ", curlCmdExecuted+"\n")
fmt.Println("Response Info:")
fmt.Println(" Error :", err)
fmt.Println(" Status Code:", resp.StatusCode())
fmt.Println(" Status :", resp.Status())
fmt.Println(" Proto :", resp.Proto())
fmt.Println(" Time :", resp.Time())
fmt.Println(" Received At:", resp.ReceivedAt())
fmt.Println(" Body :\n", resp)
fmt.Println()
fmt.Println("Request Trace Info:")
ti := resp.Request.TraceInfo()
fmt.Println(" DNSLookup :", ti.DNSLookup)
fmt.Println(" ConnTime :", ti.ConnTime)
fmt.Println(" TCPConnTime :", ti.TCPConnTime)
fmt.Println(" TLSHandshake :", ti.TLSHandshake)
fmt.Println(" ServerTime :", ti.ServerTime)
fmt.Println(" ResponseTime :", ti.ResponseTime)
fmt.Println(" TotalTime :", ti.TotalTime)
fmt.Println(" IsConnReused :", ti.IsConnReused)
fmt.Println(" IsConnWasIdle :", ti.IsConnWasIdle)
fmt.Println(" ConnIdleTime :", ti.ConnIdleTime)
fmt.Println(" RequestAttempt:", ti.RequestAttempt)
fmt.Println(" RemoteAddr :", ti.RemoteAddr.String())
Enhanced GET
client := resty.New()
resp, err := client.R().
SetQueryParams(map[string]string{
"page_no": "1",
"limit": "20",
"sort":"name",
"order": "asc",
"random":strconv.FormatInt(time.Now().Unix(), 10),
}).
SetHeader("Accept", "application/json").
SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F").
Get("/search_result")
resp, err := client.R().
SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more").
SetHeader("Accept", "application/json").
SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F").
Get("/show_product")
resp, err := client.R().
SetResult(result).
ForceContentType("application/json").
Get("v2/alpine/manifests/latest")
Various POST method combinations
client := resty.New()
resp, err := client.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}).
Post("https://myapp.com/login")
resp, err := client.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}).
Post("https://myapp.com/login")
resp, err := client.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}).
SetError(&AuthError{}).
Post("https://myapp.com/login")
resp, err := client.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}).
SetError(&AuthError{}).
Post("https://myapp.com/login")
fileBytes, _ := os.ReadFile("/Users/jeeva/mydocument.pdf")
resp, err := client.R().
SetBody(fileBytes).
SetContentLength(true).
SetAuthToken("<your-auth-token>").
SetError(&DropboxError{}).
Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf")
Sample PUT
You can use various combinations of PUT
method call like demonstrated for POST
.
client := resty.New()
resp, err := client.R().
SetBody(Article{
Title: "go-resty",
Content: "This is my article content, oh ya!",
Author: "Jeevanandam M",
Tags: []string{"article", "sample", "resty"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}).
Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH
method call like demonstrated for POST
.
client := resty.New()
resp, err := client.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}).
Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
client := resty.New()
resp, err := client.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}).
Delete("https://myapp.com/articles/1234")
resp, err := client.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}).
SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
resp, err := client.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
resp, err := client.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Override JSON & XML Marshal/Unmarshal
User could register choice of JSON/XML library into resty or write your own. By default resty registers standard encoding/json
and encoding/xml
respectively.
import jsoniter "github.com/json-iterator/go"
json := jsoniter.ConfigCompatibleWithStandardLibrary
client := resty.New().
SetJSONMarshaler(json.Marshal).
SetJSONUnmarshaler(json.Unmarshal)
client.SetXMLMarshaler(xml.Marshal).
SetXMLUnmarshaler(xml.Unmarshal)
Multipart File(s) upload
Using io.Reader
profileImgBytes, _ := os.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _ := os.ReadFile("/Users/jeeva/text-file.txt")
client := resty.New()
resp, err := client.R().
SetFileReader("profile_img", "test-img.png", bytes.NewReader(profileImgBytes)).
SetFileReader("notes", "text-file.txt", bytes.NewReader(notesBytes)).
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
}).
Post("http://myapp.com/upload")
Using File directly from Path
client := resty.New()
resp, err := client.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
resp, err := client.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
resp, err := client.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "my city",
"access_token": "C6A79608-782F-4ED0-A11D-BD82FAD829CD",
}).
Post("http://myapp.com/profile")
Sample Form submission
client := resty.New()
resp, err := client.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
resp, err := client.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
criteria := url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err := client.R().
SetFormDataFromValues(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
client := resty.New()
client.SetOutputDirectory("/Users/jeeva/Downloads")
_, err := client.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
_, err := client.R().
SetOutput("/MyDownloads/plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
Request URL Path Params
Resty provides easy to use dynamic request URL path params. Params can be set at client and request level. Client level params value can be overridden at request level.
client := resty.New()
client.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
client := resty.New()
client.OnBeforeRequest(func(c *resty.Client, req *resty.Request) error {
return nil
})
client.OnAfterResponse(func(c *resty.Client, resp *resty.Response) error {
return nil
})
OnError Hooks
Resty provides OnError hooks that may be called because:
- The client failed to send the request due to connection timeout, TLS handshake failure, etc...
- The request was retried the maximum amount of times, and still failed.
If there was a response from the server, the original error will be wrapped in *resty.ResponseError
which contains the last response received.
client := resty.New()
client.OnError(func(req *resty.Request, err error) {
if v, ok := err.(*resty.ResponseError); ok {
}
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
client := resty.New()
client.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
client.SetRedirectPolicy(resty.FlexibleRedirectPolicy(20),
resty.DomainCheckRedirectPolicy("host1.com", "host2.org", "host3.net"))
Custom Redirect Policy
Implement RedirectPolicy interface and register it with resty client. Have a look redirect.go for more information.
client := resty.New()
client.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req *http.Request, via []*http.Request) error {
return nil
}))
type CustomRedirectPolicy struct {
}
func (c *CustomRedirectPolicy) Apply(req *http.Request, via []*http.Request) error {
return nil
}
client.SetRedirectPolicy(CustomRedirectPolicy{})
Custom Root Certificates and Client Certificates
client := resty.New()
client.SetRootCertificate("/path/to/root/pemFile1.pem")
client.SetRootCertificate("/path/to/root/pemFile2.pem")
cert1, err := tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
if err != nil {
log.Fatalf("ERROR client certificate: %s", err)
}
client.SetCertificates(cert1, cert2, cert3)
Custom Root Certificates and Client Certificates from string
client.SetRootCertificateFromString("-----BEGIN CERTIFICATE-----content-----END CERTIFICATE-----")
client.SetRootCertificateFromString("-----BEGIN CERTIFICATE-----content-----END CERTIFICATE-----")
cert1, err := tls.X509KeyPair([]byte("-----BEGIN CERTIFICATE-----content-----END CERTIFICATE-----"), []byte("-----BEGIN CERTIFICATE-----content-----END CERTIFICATE-----"))
if err != nil {
log.Fatalf("ERROR client certificate: %s", err)
}
client.SetCertificates(cert1, cert2, cert3)
Proxy Settings
Default Go
supports Proxy via environment variable HTTP_PROXY
. Resty provides support via SetProxy
& RemoveProxy
.
Choose as per your need.
Client Level Proxy settings applied to all the request
client := resty.New()
client.SetProxy("http://proxyserver:8888")
client.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
client := resty.New()
client.
SetRetryCount(3).
SetRetryWaitTime(5 * time.Second).
SetRetryMaxWaitTime(20 * time.Second).
SetRetryAfter(func(client *resty.Client, resp *resty.Response) (time.Duration, error) {
return 0, errors.New("quota exceeded")
})
By default, resty will retry requests that return a non-nil error during execution.
Therefore, the above setup will result in resty retrying requests with non-nil errors up to 3 times,
with the delay increasing after each attempt.
You can optionally provide client with custom retry conditions:
client := resty.New()
client.AddRetryCondition(
func(r *resty.Response, err error) bool {
return r.StatusCode() == http.StatusTooManyRequests
},
)
The above example will make resty retry requests that end with a 429 Too Many Requests
status code.
It's important to note that when you specify conditions using AddRetryCondition
,
it will override the default retry behavior, which retries on errors encountered during the request.
If you want to retry on errors encountered during the request, similar to the default behavior,
you'll need to configure it as follows:
client := resty.New()
client.AddRetryCondition(
func(r *resty.Response, err error) bool {
return err != nil || r.StatusCode() == http.StatusTooManyRequests
},
)
Multiple retry conditions can be added.
Note that if multiple conditions are specified, a retry will occur if any of the conditions are met.
It is also possible to use resty.Backoff(...)
to get arbitrary retry scenarios
implemented. Reference.
Allow GET request with Payload
client := resty.New()
client.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
client1 := resty.New()
client1.R().Get("http://httpbin.org")
client2 := resty.New()
client2.R().Head("http://httpbin.org")
Remaining Client Settings & its Options
client := resty.New()
client.SetDebug(true)
client.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
client.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
client.SetTimeout(1 * time.Minute)
client.SetBaseURL("http://httpbin.org")
client.SetHeader("Accept", "application/json")
client.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
client.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
client.SetCookies(cookies)
client.SetQueryParam("user_id", "00001")
client.SetQueryParams(map[string]string{
"api_key": "api-key-here",
"api_secret": "api-secret",
})
client.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
client.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
client.SetBasicAuth("myuser", "mypass")
client.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
client.SetContentLength(true)
client.SetError(&Error{})
Unix Socket
unixSocket := "/var/run/my_socket.sock"
transport := http.Transport{
Dial: func(_, _ string) (net.Conn, error) {
return net.Dial("unix", unixSocket)
},
}
client := resty.New()
client.SetTransport(&transport).SetScheme("http").SetBaseURL(unixSocket)
client.R().Get("http://localhost/index.html")
Bazel Support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :resty_test
Mocking http requests using httpmock library
In order to mock the http requests when testing your application you
could use the httpmock
library.
When using the default resty client, you should pass the client to the library as follow:
client := resty.New()
httpmock.ActivateNonDefault(client.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
Resty releases versions according to Semantic Versioning
- Resty v2 does not use
gopkg.in
service for library versioning. - Resty fully adapted to
go mod
capabilities since v1.10.0
release. - Resty v1 series was using
gopkg.in
to provide versioning. gopkg.in/resty.vX
points to appropriate tagged versions; X
denotes version series number and it's a stable release for production use. For e.g. gopkg.in/resty.v0
. - Development takes place at the master branch. Although the code in master should always compile and test successfully, it might break API's. I aim to maintain backwards compatibility, but sometimes API's and behavior might be changed to fix a bug.
Contribution
I would welcome your contribution! If you find any improvement or issue you want to fix, feel free to send a pull request, I like pull requests that include test cases for fix/enhancement. I have done my best to bring pretty good code coverage. Feel free to write tests.
BTW, I'd like to know what you think about Resty
. Kindly open an issue or send me an email; it'd mean a lot to me.
Creator
Jeevanandam M. (jeeva@myjeeva.com)
Core Team
Have a look on Members page.
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.