BranchesTags

Repository files navigation

Resty

Simple REST and HTTP client library for Go (inspired by Ruby rest-client)

Features section describes in detail about Resty capabilities

Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense

News

  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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

Resty works with go1.3 and above.

Included Batteries

  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).

Installation

Stable Version - Production Ready

Please refer section Versioning for detailed info.

go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1

Latest Version - Development Edge

# install the latest & greatest library
go get -u github.com/go-resty/resty

It might be beneficial for your project 😄

Resty author also published following projects for Go Community.

  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.

Usage

The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.

Import resty into your code and refer it as resty.

import"gopkg.in/resty.v1"

Simple GET

// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/

Enhanced GET

resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")

Various POST method combinations

// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type

Sample PUT

You can use various combinations of PUT method call like demonstrated for POST.

// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")

Sample PATCH

You can use various combinations of PATCH method call like demonstrated for POST.

// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")

Sample DELETE, HEAD, OPTIONS

// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")

Multipart File(s) upload

Using io.Reader

profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")

Using File directly from Path

// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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

// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")

Save HTTP Response into File

// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.

resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details

Request and Response Middleware

Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.

// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})

Redirect Policy

Resty provides few ready to use redirect policy(s) also it supports multiple policies together.

// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.

// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})

Custom Root Certificates and Client Certificates

// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)

Proxy Settings - Client as well as at Request Level

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

// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()

Retries

Resty uses backoff to increase retry intervals after each attempt.

Usage example:

// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)

Above setup will result in resty retrying requests returned non nil error up to 3 times with delay increased after each attempt.

You can optionally provide client with custom retry conditions:

resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)

Above example will make resty retry requests ended with 429 Too Many Requests status code.

Multiple retry conditions can be added.

It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios implemented. Reference.

Choose REST or HTTP mode

// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()

Allow GET request with Payload

// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)

Wanna Multiple Clients

// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!

Remaining Client Settings & its Options

// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})

Unix Socket

unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")

Bazel support

Resty can be built, tested and depended upon via Bazel. For example, to run all tests:

bazel test :go_default_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:

httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())

More detailed example of mocking resty http requests using ginko could be found here.

Versioning

resty releases versions according to Semantic 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)

Contributors

Have a look on Contributors page.

License

Resty released under MIT license, refer LICENSE file.

About

Simple REST and HTTP client library for Go

godoc.org/github.com/go-resty/resty

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
BranchesTags
Repository files navigation
Resty
Simple REST and HTTP client library for Go (inspired by Ruby rest-client)
Features section describes in detail about Resty capabilities
Build StatusCode CoverageGo Report CardRelease VersionGoDocLicense
News
  • v1.6 released and tagged on May 28, 2018.
  • v1.0 released - 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; v1.0 was released on Sep 25, 2017. 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
  • 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 go1.7 and above
  • Authorization option of BasicAuth and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and REST mode. Default is REST
    • HTTP - default up to 10 redirects and no automatic response unmarshal
    • REST - defaults to no redirects and automatic response marshal/unmarshal for JSON & XML
  • 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 middlewares
    • Create Multiple clients if you want to resty.New()
    • Supports http.RoundTripper implementation, see SetTransport
    • goroutine concurrent safe
    • REST and HTTP modes
    • Debug mode - clean and informative logging presentation
    • Gzip - Go does it automatically also resty 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
Resty works with go1.3 and above.
Included Batteries
  • Redirect Policies - see how to use
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Retry Mechanism how to use
    • Backoff Retry
    • Conditional Retry
  • SRV Record based request instead of Host URL how to use
  • etc (upcoming - throw your idea's here).
Installation
Stable Version - Production Ready
Please refer section Versioning for detailed info.
go.mod
require github.com/go-resty/resty v1.6
go get
go get -u gopkg.in/resty.v1
Latest Version - Development Edge
# install the latest & greatest library
go get -u github.com/go-resty/resty
It might be beneficial for your project 😄
Resty author also published following projects for Go Community.
  • aah framework - A secure, flexible, rapid Go web framework.
  • go-model - Robust & Easy to use model mapper and utility methods for Go struct.
Usage
The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.
Import resty into your code and refer it as resty.
import"gopkg.in/resty.v1"
Simple GET
// GET requestresp, err:=resty.R().Get("http://httpbin.org/get")
// explore response objectfmt.Printf("\nError: %v", err)
fmt.Printf("\nResponse Status Code: %v", resp.StatusCode())
fmt.Printf("\nResponse Status: %v", resp.Status())
fmt.Printf("\nResponse Time: %v", resp.Time())
fmt.Printf("\nResponse Received At: %v", resp.ReceivedAt())
fmt.Printf("\nResponse Body: %v", resp) // or resp.String() or string(resp.Body())// more.../* OutputError: <nil>Response Status Code: 200Response Status: 200 OKResponse Time: 644.290186msResponse Received At: 2015-09-15 12:05:28.922780103 -0700 PDTResponse Body: { "args": {}, "headers": { "Accept-Encoding": "gzip", "Host": "httpbin.org", "User-Agent": "go-resty v0.1 - https://github.com/go-resty/resty" }, "origin": "0.0.0.0", "url": "http://httpbin.org/get"}*/
Enhanced GET
resp, err:=resty.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")
// Sample of using Request.SetQueryString methodresp, err:=resty.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")
Various POST method combinations
// POST JSON string// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST []byte array// No need to set content type, if you have client level settingresp, err:=resty.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).Post("https://myapp.com/login")
// POST Struct, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST Map, default is JSON content type. No need to set oneresp, err:=resty.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}). // or SetResult(AuthSuccess{}).SetError(&AuthError{}). // or SetError(AuthError{}).Post("https://myapp.com/login")
// POST of raw bytes for file upload. For example: upload file to DropboxfileBytes, _:=ioutil.ReadFile("/Users/jeeva/mydocument.pdf")
// See we are not setting content-type header, since go-resty automatically detects Content-Type for youresp, err:=resty.R().
SetBody(fileBytes).
SetContentLength(true). // Dropbox expects this valueSetAuthToken("<your-auth-token>").
SetError(&DropboxError{}). // or SetError(DropboxError{}).Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // for upload Dropbox supports PUT too// Note: resty detects Content-Type for request body/payload if content type header is not set.// * For struct and map data type defaults to 'application/json'// * Fallback is plain text content type
Sample PUT
You can use various combinations of PUT method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.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{}). // or SetError(Error{}).Put("https://myapp.com/article/1234")
Sample PATCH
You can use various combinations of PATCH method call like demonstrated for POST.
// Note: This is one sample of PUT method usage, refer POST for more combination// Request goes as JSON content type// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetBody(Article{
Tags: []string{"new tag1", "new tag2"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Patch("https://myapp.com/articles/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).Delete("https://myapp.com/articles/1234")
// DELETE a articles with payload/body as a JSON string// No need to set auth token, error, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}). // or SetError(Error{}).SetHeader("Content-Type", "application/json").
SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
Delete("https://myapp.com/articles")
// HEAD of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Head("https://myapp.com/videos/hi-res-video")
// OPTIONS of resource// No need to set auth token, if you have client level settingsresp, err:=resty.R().
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
Options("https://myapp.com/servers/nyc-dc-01")
Multipart File(s) upload
Using io.Reader
profileImgBytes, _:=ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _:=ioutil.ReadFile("/Users/jeeva/text-file.txt")
resp, err:=dclr().
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(t"http://myapp.com/upload")
Using File directly from Path
// Single file scenarioresp, err:=resty.R().
SetFile("profile_img", "/Users/jeeva/test-img.png").
Post("http://myapp.com/upload")
// Multiple files scenarioresp, err:=resty.R().
SetFiles(map[string]string{
"profile_img": "/Users/jeeva/test-img.png",
"notes": "/Users/jeeva/text-file.txt",
}).
Post("http://myapp.com/upload")
// Multipart of form fields and filesresp, err:=resty.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
// just mentioning about POST as an example with simple flow// User Loginresp, err:=resty.R().
SetFormData(map[string]string{
"username": "jeeva",
"password": "mypass",
}).
Post("http://myapp.com/login")
// Followed by profile updateresp, err:=resty.R().
SetFormData(map[string]string{
"first_name": "Jeevanandam",
"last_name": "M",
"zip_code": "00001",
"city": "new city update",
}).
Post("http://myapp.com/profile")
// Multi value form datacriteria:= url.Values{
"search_criteria": []string{"book", "glass", "pencil"},
}
resp, err:=resty.R().
SetMultiValueFormData(criteria).
Post("http://myapp.com/search")
Save HTTP Response into File
// Setting output directory path, If directory not exists then resty creates one!// This is optional one, if you're planning using absoule path in// `Request.SetOutput` and can used together.resty.SetOutputDirectory("/Users/jeeva/Downloads")
// HTTP response gets saved into file, similar to curl -o flag_, err:=resty.R().
SetOutput("plugin/ReplyWithHeader-v5.1-beta.zip").
Get("http://bit.ly/1LouEKr")
// OR using absolute path// Note: output directory path is not used for absoulte path_, err:=resty.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.
resty.R().SetPathParams(map[string]string{
"userId": "sample@sample.com",
"subAccountId": "100002",
}).
Get("/v1/users/{userId}/{subAccountId}/details")
// Result:// Composed URL - /v1/users/sample@sample.com/100002/details
Request and Response Middleware
Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.
// Registering Request Middlewareresty.OnBeforeRequest(func(c*resty.Client, req*resty.Request) error {
// Now you have access to Client and current Request object// manipulate it as per your needreturnnil// if its success otherwise return error
})
// Registering Response Middlewareresty.OnAfterResponse(func(c*resty.Client, resp*resty.Response) error {
// Now you have access to Client and current Response object// manipulate it as per your needreturnnil// if its success otherwise return error
})
Redirect Policy
Resty provides few ready to use redirect policy(s) also it supports multiple policies together.
// Assign Client Redirect Policy. Create one as per you needresty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
// Wanna multiple policies such as redirect count, domain name check, etcresty.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.
// Using raw func into resty.SetRedirectPolicyresty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}))
//---------------------------------------------------// Using struct create more flexible redirect policytypeCustomRedirectPolicystruct {
// variables goes here
}
func (c*CustomRedirectPolicy) Apply(req*http.Request, via []*http.Request) error {
// Implement your logic here// return nil for continue redirect otherwise return error to stop/prevent redirectreturnnil
}
// Registering in restyresty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
Custom Root Certificates and Client Certificates
// Custom Root certificates, just supply .pem file.// you can add one or more root certificates, its get appendedresty.SetRootCertificate("/path/to/root/pemFile1.pem")
resty.SetRootCertificate("/path/to/root/pemFile2.pem")
// ... and so on!// Adding Client Certificates, you add one or more certificates// Sample for creating certificate object// Parsing public/private key pair from a pair of files. The files must contain PEM encoded data.cert1, err:=tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
iferr!=nil {
log.Fatalf("ERROR client certificate: %s", err)
}
// ...// You add one or more certificatesresty.SetCertificates(cert1, cert2, cert3)
Proxy Settings - Client as well as at Request Level
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
// Setting a Proxy URL and Portresty.SetProxy("http://proxyserver:8888")
// Want to remove proxy settingresty.RemoveProxy()
Retries
Resty uses backoff
to increase retry intervals after each attempt.
Usage example:
// Retries are configured per clientresty.
// Set retry count to non zero to enable retriesSetRetryCount(3).
// You can override initial retry wait time.// Default is 100 milliseconds.SetRetryWaitTime(5*time.Second).
// MaxWaitTime can be overridden as well.// Default is 2 seconds.SetRetryMaxWaitTime(20*time.Second)
Above setup will result in resty retrying requests returned non nil error up to
3 times with delay increased after each attempt.
You can optionally provide client with custom retry conditions:
resty.AddRetryCondition(
// Condition function will be provided with *resty.Response as a// parameter. It is expected to return (bool, error) pair. Resty will retry// in case condition returns true or non nil error.func(r*resty.Response) (bool, error) {
returnr.StatusCode() ==http.StatusTooManyRequests, nil
},
)
Above example will make resty retry requests ended with 429 Too Many Requests
status code.
Multiple retry conditions can be added.
It is also possible to use resty.Backoff(...) to get arbitrary retry scenarios
implemented. Reference.
Choose REST or HTTP mode
// REST mode. This is Default.resty.SetRESTMode()
// HTTP moderesty.SetHTTPMode()
Allow GET request with Payload
// Allow GET request with Payload. This is disabled by default.resty.SetAllowGetMethodPayload(true)
Wanna Multiple Clients
// Here you go!// Client 1client1:=resty.New()
client1.R().Get("http://httpbin.org")
// ...// Client 2client2:=resty.New()
client2.R().Head("http://httpbin.org")
// ...// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level//--------------------------------// Enable debug moderesty.SetDebug(true)
// Using you custom log writerlogFile, _:=os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
resty.SetLogger(logFile)
// Assign Client TLSClientConfig// One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dialresty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })
// or One can disable security check (https)resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })
// Set client timeout as per your needresty.SetTimeout(1*time.Minute)
// You can override all below settings and options at request level if you want to//--------------------------------------------------------------------------------// Host URL for all request. So you can use relative URL in the requestresty.SetHostURL("http://httpbin.org")
// Headers for all requestresty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
"Content-Type": "application/json",
"User-Agent": "My custom User Agent String",
})
// Cookies for all requestresty.SetCookie(&http.Cookie{
Name:"go-resty",
Value:"This is cookie value",
Path: "/",
Domain: "sample.com",
MaxAge: 36000,
HttpOnly: true,
Secure: false,
})
resty.SetCookies(cookies)
// URL query parameters for all requestresty.SetQueryParam("user_id", "00001")
resty.SetQueryParams(map[string]string{ // sample of those who use this manner"api_key": "api-key-here",
"api_secert": "api-secert",
})
resty.R().SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")
// Form data for all request. Typically used with POST and PUTresty.SetFormData(map[string]string{
"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
})
// Basic Auth for all requestresty.SetBasicAuth("myuser", "mypass")
// Bearer Auth Token for all requestresty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")
// Enabling Content length value for all requestresty.SetContentLength(true)
// Registering global Error object structure for JSON/XML requestresty.SetError(&Error{}) // or resty.SetError(Error{})
Unix Socket
unixSocket:="/var/run/my_socket.sock"// Create a Go's http.Transport so we can set it in resty.transport:= http.Transport{
Dial: func(_, _string) (net.Conn, error) {
returnnet.Dial("unix", unixSocket)
},
}
// Set the previous transport that we created, set the scheme of the communication to the// socket and set the unixSocket as the HostURL.r:=resty.New().SetTransport(&transport).SetScheme("http").SetHostURL(unixSocket)
// No need to write the host's URL on the request, just the path.r.R().Get("/index.html")
Bazel support
Resty can be built, tested and depended upon via Bazel.
For example, to run all tests:
bazel test :go_default_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:
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
More detailed example of mocking resty http requests using ginko could be found here.
Versioning
resty releases versions according to Semantic 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)
Contributors
Have a look on Contributors page.
License
Resty released under MIT license, refer LICENSE file.
About
Simple REST and HTTP client library for Go
godoc.org/github.com/go-resty/resty
Resources
Readme
MIT license
Activity
Custom properties
Stars
0 stars
Watchers
2 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages