resty

package module
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2015 License: MIT Imports: 23 Imported by: 0

README

resty Build Status GoCover GoDoc License

Simple HTTP and REST client for Go inspired by Ruby rest-client. Provides notable features - robust request body input, auto marshal & unmarshal, request and response middlewares, custom & extensible redirect policy (multiple policies can be applied), etc.

Features
  • Get, Post, Put, Delete, Head, Patch and Options
  • Simple methods/chainable methods for settings and request
  • Request Body can be string, []byte, struct and map
    • Auto detect Content-Type
  • 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
    • Have a look godoc
  • Automatic marshal and unmarshal for JSON and XML content type
    • Default is JSON, if you supply struct/map without header Content-Type
  • Easy to upload single or multiple files via multipart/form-data
  • Cookies for your request and CookieJar support
  • Authorization option of Basic and Bearer token
  • Set request ContentLength value for all request or particular request
  • Choose between HTTP and RESTful mode. Default is RESTful
    • HTTP - default upto 10 redirects and no automaic response unmarshal
    • RESTful - default no redirects and automatic response unmarshal for JSON & XML
  • Client settings like Timeout, RedirectPolicy, Proxy and TLSClientConfig
  • Client API design
    • Have client level settings & options and also override at Request level if you want to
    • Request and Response middleware
    • Create Multiple clients if want to resty.New()
    • goroutine concurrent safe
    • Debug mode - clean and informative logging presentation
    • Gzip - I'm not doing anything here. Go does it automatically
  • Well tested client library

resty tested with Go 1.2 and above.

Included Batteries
  • Redirect Policies
    • NoRedirectPolicy
    • FlexibleRedirectPolicy
    • DomainCheckRedirectPolicy
    • etc. more info
  • Write Cookies to file from CookiesJar (upcoming)
  • etc.

Installation

Stable
go get gopkg.in/resty.v0
Latest
go get github.com/go-resty/resty

Usage

Following samples will assist you to become as much 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.v0"
Simple GET
// GET request
resp, err := resty.R().Get("http://httpbin.org/get")

// explore response object
fmt.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 Recevied At: %v", resp.ReceivedAt)
fmt.Printf("\nResponse Body: %v", resp)
// more...

/* Output
Error: <nil>
Response Status Code: 200
Response Status: 200 OK
Response Time: 644.290186ms
Response Recevied At: 2015-09-15 12:05:28.922780103 -0700 PDT
Response 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"
}
*/
Ehanced 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")
Various POST method combinations
// POST JSON string
// No need to set content type, if you have client level setting
resp, 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 setting
resp, 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 one
resp, 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 one
resp, 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 Dropbox
file, _ := os.Open("/Users/jeeva/mydocument.pdf")
fileBytes, _ := ioutil.ReadAll(file)

// See we are not setting content-type header, since go-resty automatically detects Content-Type for you
resp, err := resty.R().
      SetBody(fileBytes).
      SetContentLength(true).          // Dropbox expects this value
      SetAuthToken("<you-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
Sample PUT

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

// Just one sample of PUT, refer POST for more combination
// request goes as JSON content type
// No need to set auth token, error, if you have client level settings
resp, 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.

// Just one sample of PATCH, refer POST for more combination
// request goes as JSON content type
// No need to set auth token, error, if you have client level settings
resp, 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/article/1234")
Sample DELETE, HEAD, OPTIONS
// DELETE a article
// No need to set auth token, error, if you have client level settings
resp, err := resty.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // or SetError(Error{}).
      Delete("https://myapp.com/article/1234")

// HEAD of resource
// No need to set auth token, if you have client level settings
resp, err := resty.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      Head("https://myapp.com/video/hi-res-video")

// OPTIONS of resource
// No need to set auth token, if you have client level settings
resp, err := resty.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      Options("https://myapp.com/server/nyc-dc-01")
Multipart File(s) upload
// Single file scenario
resp, err := resty.R().
      SetFile("profile_img", "/Users/jeeva/test-img.png").
      Post("http://myapp.com/upload")

// Multiple files scenario
resp, 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 files
resp, 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 submision
// just mentioning about POST as an example with simple flow
// User Login
resp, err := resty.R().
      SetFormData(map[string]string{
        "username": "jeeva", 
        "password": "mypass",
      }).
      Post("http://myapp.com/login")

// Followed by profile update
resp, 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")
Request and Response Middleware
// Registering Request Middleware 
resty.OnBeforeRequest(func(c *Client, r *Request) error {
    // Now you have access to Client and current Request object
    // manipulate it as per your need

    return nil  // if its success otherwise return error
  })

// Registering Response Middleware
resty.OnAfterResponse(func(c *Client, r *Response) error {
    // Now you have access to Client and current Response object
    // manipulate it as per your need

    return nil  // 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 need
resty.SetRedirectPolicy(FlexibleRedirectPolicy(15))

// Wanna multiple policies such as redirect count, domain name check, etc
resty.SetRedirectPolicy(FlexibleRedirectPolicy(20), 
                        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.SetRedirectPolicy
resty.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 redirect
  return nil
}))

//---------------------------------------------------

// Using struct create more flexible redirect policy
type CustomRedirectPolicy struct {
  // 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 redirect
  return nil
}

// Registering in resty
resty.SetRedirectPolicy(CustomRedirectPolicy{/* initial variables */})
Proxy Settings

Default Go supports Proxy via environment variable HTTP_PROXY. Resty provides support via SetProxy & RemoveProxy. Choose as per your need.

// Setting a Proxy URL and Port
resty.SetProxy("http://proxyserver:8888")

// Want to remove proxy setting
resty.RemoveProxy()
Choose REST or HTTP mode
// HTTP mode
resty.SetHTTPMode() 

// REST mode. Default one
resty.SetRESTMode()
Wanna Multiple Clients
// Here you go!
// Client 1
client1 := resty.New()
client1.R().Get("http://httpbin.org")
// ...

// Client 2
client2 := resty.New()
client1.R().Head("http://httpbin.org")
// ...

// Bend it as per your need!!!
Remaining Client Settings & its Options
// Unique settings at Client level
//--------------------------------
// Enable debug mode
resty.SetDebug(true)

// Using you custom log writer
logFile, _ := 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_Dial
resty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })

// or One can disable security check (https)
resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })

// Set client timeout as per your need
resty.SetTimeout(time.Duration(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 request
resty.SetHostURL("http://httpbin.org")

// Headers for all request
resty.SetHeader("Accept", "application/json")
resty.SetHeaders(map[string]string{
        "Content-Type": "application/json",
        "User-Agent": "My cutsom User Agent String",
      })

// Cookies for all request
resty.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 request
resty.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",
    })

// Form data for all request. Typically used with POST and PUT
resty.SetFormData(map[string]string{
    "access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
  })

// Basic Auth for all request
resty.SetBasicAuth("myuser", "mypass")

// Bearer Auth Token for all request
resty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")

// Enabling Content length value for all request
resty.SetContentLength(true)

// Registering global Error object structure for JSON/XML request
resty.SetError(&Error{})    // or resty.SetError(Error{})
Versioning
Contributing

Welcome! If you find any improvement or issue you want to fix. Feel free to send a pull request, I like pull requests that include tests case for fix/enhancement. Did my best to bring pretty good code coverage and feel free to write tests.

BTW, I'd like to know what you think about go-resty. Kindly open an issue or send me an email; it'd mean a lot to me.

License

resty released under MIT license, refer LICENSE file.

Documentation

Overview

Package resty provides simple HTTP and REST client for Go inspired by Ruby rest-client.

Index

Constants

View Source 
const (
	// GET HTTP method
	GET = "GET"

	// POST HTTP method
	POST = "POST"

	// PUT HTTP method
	PUT = "PUT"

	// DELETE HTTP method
	DELETE = "DELETE"

	// PATCH HTTP method
	PATCH = "PATCH"

	// HEAD HTTP method
	HEAD = "HEAD"

	// OPTIONS HTTP method
	OPTIONS = "OPTIONS"
)

Variables

View Source 
var Version = "0.2.1"

go-resty version no

Functions

func DetectContentType 

func DetectContentType(body interface{}) string

DetectContentType method is used to figure out `Request.Body` content type for request header

func IsJSONType 

func IsJSONType(ct string) bool

IsJSONType method is to check JSON content type or not

func IsStringEmpty 

func IsStringEmpty(str string) bool

IsStringEmpty method tells whether given string is empty or not

func IsXMLType 

func IsXMLType(ct string) bool

IsXMLType method is to check XML content type or not

func Mode 

func Mode() string

Mode method returns the current client mode. See Client.Mode for more information.

func Unmarshal 

func Unmarshal(ct string, b []byte, d interface{}) (err error)

Unmarshal content into object from JSON or XML

Types

type Client 

type Client struct {
	HostURL    string
	QueryParam url.Values
	FormData   url.Values
	Header     http.Header
	UserInfo   *User
	Token      string
	Cookies    []*http.Cookie
	Error      interface{}
	Debug      bool
	Log        *log.Logger
	// contains filtered or unexported fields
}

Client type is used for HTTP/RESTful global values for all request raised from the client 

var DefaultClient *Client

The default Client

func New 

func New() *Client

New creates a new go-resty client 

For Example:
client1 := resty.New()

client2 := resty.New()

func OnAfterResponse 

func OnAfterResponse(m func(*Client, *Response) error) *Client

OnAfterResponse method sets response middleware. See Client.OnAfterResponse for more information.

func OnBeforeRequest 

func OnBeforeRequest(m func(*Client, *Request) error) *Client

OnBeforeRequest method sets request middleware. See Client.OnBeforeRequest for more information.

func RemoveProxy 

func RemoveProxy() *Client

RemoveProxy method removes the proxy configuration. See Client.RemoveProxy for more information.

func SetAuthToken 

func SetAuthToken(token string) *Client

SetAuthToken method sets bearer auth token header. See Client.SetAuthToken for more information.

func SetBasicAuth 

func SetBasicAuth(username, password string) *Client

SetBasicAuth method sets the basic authentication header. See Client.SetBasicAuth for more information.

func SetContentLength 

func SetContentLength(l bool) *Client

SetContentLength method enables `Content-Length` value. See Client.SetContentLength for more information.

func SetCookie 

func SetCookie(hc *http.Cookie) *Client

SetCookie sets single cookie object. See Client.SetCookie for more information.

func SetCookies 

func SetCookies(cs []*http.Cookie) *Client

SetCookies sets multiple cookie object. See Client.SetCookies for more information.

func SetDebug 

func SetDebug(d bool) *Client

SetDebug method enables the debug mode. See Client.SetDebug for more information.

func SetError 

func SetError(err interface{}) *Client

SetError method is to register the global or client common `Error` object. See Client.SetError for more information.

func SetFormData 

func SetFormData(data map[string]string) *Client

SetFormData method sets Form parameters and its values. See Client.SetFormData for more information.

func SetHTTPMode 

func SetHTTPMode() *Client

SetHTTPMode method sets go-resty mode into HTTP. See Client.SetMode for more information.

func SetHeader 

func SetHeader(header, value string) *Client

SetHeader sets single header. See Client.SetHeader for more information.

func SetHeaders 

func SetHeaders(headers map[string]string) *Client

SetHeaders sets multiple headers. See Client.SetHeaders for more information.

func SetHostURL 

func SetHostURL(url string) *Client

SetHostURL sets Host URL. See Client.SetHostURL for more information.

func SetLogger 

func SetLogger(w io.Writer) *Client

SetLogger method sets given writer for logging. See Client.SetLogger for more information.

func SetProxy 

func SetProxy(proxyURL string) *Client

SetProxy method sets Proxy for request. See Client.SetProxy for more information.

func SetQueryParam 

func SetQueryParam(param, value string) *Client

SetQueryParam method sets single paramater and its value. See Client.SetQueryParam for more information.

func SetQueryParams 

func SetQueryParams(params map[string]string) *Client

SetQueryParams method sets multiple paramaters and its value. See Client.SetQueryParams for more information.

func SetRESTMode 

func SetRESTMode() *Client

SetRESTMode method sets go-resty mode into RESTful. See Client.SetMode for more information.

func SetRedirectPolicy 

func SetRedirectPolicy(policies ...interface{}) *Client

SetRedirectPolicy method sets the client redirect poilicy. See Client.SetRedirectPolicy for more information.

func SetTLSClientConfig 

func SetTLSClientConfig(config *tls.Config) *Client

SetTLSClientConfig method sets TLSClientConfig for underling client Transport. See Client.SetTLSClientConfig for more information.

func SetTimeout 

func SetTimeout(timeout time.Duration) *Client

SetTimeout method sets timeout for request. See Client.SetTimeout for more information.

func (*Client) Mode 

func (c *Client) Mode() string

Mode method returns the current client mode. Typically its a "http" or "rest". Default is "rest"

func (*Client) OnAfterResponse 

func (c *Client) OnAfterResponse(m func(*Client, *Response) error) *Client

OnAfterResponse method sets response middleware into the after response chain. Once we receive response from host server, default `go-resty` response middleware gets applied and then user assigened response middlewares applied. 

resty.OnAfterResponse(func(c *Client, r *Response) error {
		// Now you have access to Client and Response instance
		// manipulate it as per your need

		return nil 	// if its success otherwise return error
	})

func (*Client) OnBeforeRequest 

func (c *Client) OnBeforeRequest(m func(*Client, *Request) error) *Client

OnBeforeRequest method sets request middleware into the before request chain. Its gets applied after default `go-resty` request middlewares and before request been sent from `go-resty` to host server. 

resty.OnBeforeRequest(func(c *Client, r *Request) error {
		// Now you have access to Client and Request instance
		// manipulate it as per your need

		return nil 	// if its success otherwise return error
	})

func (*Client) R 

func (c *Client) R() *Request

R method creates a request instance, its used for Get, Post, Put, Delete, Patch, Head and Options.

func (*Client) RemoveProxy 

func (c *Client) RemoveProxy() *Client

RemoveProxy method removes the proxy configuration from resty client 

resty.RemoveProxy()

func (*Client) SetAuthToken 

func (c *Client) SetAuthToken(token string) *Client

SetAuthToken method sets bearer auth token header in the HTTP request. For exmaple - 

Authorization: Bearer <auth-token-value-comes-here>

For example: To set auth token BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F 

resty.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")

This bearer auth token gets added to all the request rasied from this client instance. Also it can be overriden or set one at the request level is supported, see `resty.R().SetAuthToken`.

func (*Client) SetBasicAuth 

func (c *Client) SetBasicAuth(username, password string) *Client

SetBasicAuth method sets the basic authentication header in the HTTP request. For example - 

Authorization: Basic <base64-encoded-value>

For example: To set the header for username "go-resty" and password "welcome" 

resty.SetBasicAuth("go-resty", "welcome")

This basic auth information gets added to all the request rasied from this client instance. Also it can be overriden or set one at the request level is supported, see `resty.R().SetBasicAuth`.

func (*Client) SetContentLength 

func (c *Client) SetContentLength(l bool) *Client

SetContentLength method enables the HTTP header `Content-Length` value for every request. By default go-resty won't set `Content-Length`. 

resty.SetContentLength(true)

Also you have an option to enable for particular request. See `resty.R().SetContentLength`

func (*Client) SetCookie 

func (c *Client) SetCookie(hc *http.Cookie) *Client

SetCookie method sets a single cookie in the client instance. These cookies will be added to all the request raised from this client instance. 

resty.SetCookie(&http.Cookie{
			Name:"go-resty",
			Value:"This is cookie value",
			Path: "/",
			Domain: "sample.com",
			MaxAge: 36000,
			HttpOnly: true,
			Secure: false,
		})

func (*Client) SetCookies 

func (c *Client) SetCookies(cs []*http.Cookie) *Client

SetCookies method sets an array of cookies in the client instance. These cookies will be added to all the request raised from this client instance. 

cookies := make([]*http.Cookie, 0)

cookies = append(cookies, &http.Cookie{
			Name:"go-resty-1",
			Value:"This is cookie 1 value",
			Path: "/",
			Domain: "sample.com",
			MaxAge: 36000,
			HttpOnly: true,
			Secure: false,
		})

cookies = append(cookies, &http.Cookie{
			Name:"go-resty-2",
			Value:"This is cookie 2 value",
			Path: "/",
			Domain: "sample.com",
			MaxAge: 36000,
			HttpOnly: true,
			Secure: false,
		})

// Setting a cookies into resty
resty.SetCookies(cookies)

func (*Client) SetDebug 

func (c *Client) SetDebug(d bool) *Client

SetDebug method enables the debug mode on `go-resty` client. Client logs details of every request and response. For `Request` it logs information such as HTTP verb, Relative URL path, Host, Headers, Body if it has one. For `Response` it logs information such as Status, Response Time, Headers, Body if it has one.

func (*Client) SetError 

func (c *Client) SetError(err interface{}) *Client

SetError method is to register the global or client common `Error` object into go-resty. It is used for automatic unmarshalling if response status code is greater than 399 and content type either JSON or XML. Can be pointer or non-pointer. 

resty.SetError(&Error{})
// OR
resty.SetError(Error{})

func (*Client) SetFormData 

func (c *Client) SetFormData(data map[string]string) *Client

SetFormData method sets Form parameters and its values in the client instance. It's applicable only HTTP method `POST` and `PUT` and requets content type would be set as `application/x-www-form-urlencoded`. These form data will be added to all the request raised from this client instance. Also it can be overridden at request level form data, see `resty.R().SetFormData`. 

resty.SetFormData(map[string]string{
		"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
		"user_id": "3455454545",
	})

func (*Client) SetHTTPMode 

func (c *Client) SetHTTPMode() *Client

SetHTTPMode method sets go-resty mode into HTTP

func (*Client) SetHeader 

func (c *Client) SetHeader(header, value string) *Client

SetHeader method sets a single header field and its value in the client instance. These headers will be applied to all requests raised from this client instance. Also it can be overridden at request level header options, see `resty.R().SetHeader` or `resty.R().SetHeaders`.

For Example: To set `Content-Type` and `Accept` as `application/json` 

resty.
	SetHeader("Content-Type", "application/json").
	SetHeader("Accept", "application/json")

func (*Client) SetHeaders 

func (c *Client) SetHeaders(headers map[string]string) *Client

SetHeaders method sets multiple headers field and its values at one go in the client instance. These headers will be applied to all requests raised from this client instance. Also it can be overridden at request level headers options, see `resty.R().SetHeaders` or `resty.R().SetHeader`.

For Example: To set `Content-Type` and `Accept` as `application/json` 

resty.SetHeaders(map[string]string{
		"Content-Type": "application/json",
		"Accept": "application/json",
	})

func (*Client) SetHostURL 

func (c *Client) SetHostURL(url string) *Client

SetHostURL method is to set Host URL in the client instance. It will be used with request raised from this client with relative URL

func (*Client) SetLogger 

func (c *Client) SetLogger(w io.Writer) *Client

SetLogger method sets given writer for logging go-resty request and response details. Default is os.Stderr 

file, _ := os.OpenFile("/Users/jeeva/go-resty.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)

resty.SetLogger(file)

func (*Client) SetMode 

func (c *Client) SetMode(mode string) *Client

SetMode method sets go-resty client mode to given value such as 'http' & 'rest'. 

RESTful:
	- No Redirect
	- Automatic response unmarshal if it is JSON or XML
HTML:
	- Up to 10 Redirects
	- No automatic unmarshall. Response will be treated as `response.String()`

If you want more redirects, use FlexibleRedirectPolicy 

resty.SetRedirectPolicy(FlexibleRedirectPolicy(20))

func (*Client) SetProxy 

func (c *Client) SetProxy(proxyURL string) *Client

SetProxy method sets the Proxy URL and Port for resty client. 

resty.SetProxy("http://proxyserver:8888")

Alternative: Without this `SetProxy` method, you can also set Proxy via environment variable. By default `Go` uses setting from `HTTP_PROXY`.

func (*Client) SetQueryParam 

func (c *Client) SetQueryParam(param, value string) *Client

SetQueryParam method sets single paramater and its value in the client instance. It will be formed as query string for the request. For example: `search=kitchen%20papers&size=large` in the URL after `?` mark. These query params will be added to all the request raised from this client instance. Also it can be overridden at request level Query Param options, see `resty.R().SetQueryParam` or `resty.R().SetQueryParams`. 

resty.
	SetQueryParam("search", "kitchen papers").
	SetQueryParam("size", "large")

func (*Client) SetQueryParams 

func (c *Client) SetQueryParams(params map[string]string) *Client

SetQueryParams method sets multiple paramaters and its values at one go in the client instance. It will be formed as query string for the request. For example: `search=kitchen%20papers&size=large` in the URL after `?` mark. These query params will be added to all the request raised from this client instance. Also it can be overridden at request level Query Param options, see `resty.R().SetQueryParams` or `resty.R().SetQueryParam`. 

resty.SetQueryParams(map[string]string{
		"search": "kitchen papers",
		"size": "large",
	})

func (*Client) SetRESTMode 

func (c *Client) SetRESTMode() *Client

SetRESTMode method sets go-resty mode into RESTful

func (*Client) SetRedirectPolicy 

func (c *Client) SetRedirectPolicy(policies ...interface{}) *Client

SetRedirectPolicy method sets the client redirect poilicy. go-resty provides ready to use redirect policies. Wanna create one for yourself refer `redirect.go`. 

resty.SetRedirectPolicy(FlexibleRedirectPolicy(20))

// Need multiple redirect policies together
resty.SetRedirectPolicy(FlexibleRedirectPolicy(20), DomainCheckRedirectPolicy("host1.com", "host2.net"))

func (*Client) SetTLSClientConfig 

func (c *Client) SetTLSClientConfig(config *tls.Config) *Client

SetTLSClientConfig method sets TLSClientConfig for underling client Transport.

For example: One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dial 

resty.SetTLSClientConfig(&tls.Config{ RootCAs: roots })

or One can disable security check (https) 

resty.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true })

func (*Client) SetTimeout 

func (c *Client) SetTimeout(timeout time.Duration) *Client

SetTimeout method sets timeout for request raised from client 

resty.SetTimeout(time.Duration(1 * time.Minute))

type RedirectPolicy 

type RedirectPolicy interface {
	Apply(req *http.Request, via []*http.Request) error
}

RedirectPolicy to regulate the redirects in the resty client. Objects implementing the RedirectPolicy interface can be registered as

Apply function should return nil to continue the redirect jounery, otherwise return error to stop the redirect.

func DomainCheckRedirectPolicy 

func DomainCheckRedirectPolicy(hostnames ...string) RedirectPolicy

DomainCheckRedirectPolicy is convenient method to define domain name redirect rule in resty client. 

resty.SetRedirectPolicy(DomainCheckRedirectPolicy("host1.com", "host2.org", "host3.net"))

func FlexibleRedirectPolicy 

func FlexibleRedirectPolicy(noOfRedirect int) RedirectPolicy

FlexibleRedirectPolicy is convenient method to create No of redirect policy for HTTP client. 

resty.SetRedirectPolicy(FlexibleRedirectPolicy(20))

func NoRedirectPolicy 

func NoRedirectPolicy() RedirectPolicy

NoRedirectPolicy is used to disable redirects in the HTTP client 

resty.SetRedirectPolicy(NoRedirectPolicy())

type RedirectPolicyFunc 

type RedirectPolicyFunc func(*http.Request, []*http.Request) error

The RedirectPolicyFunc type is an adapter to allow the use of ordinary functions as RedirectPolicy. If f is a function with the appropriate signature, RedirectPolicyFunc(f) is a RedirectPolicy object that calls f.

func (RedirectPolicyFunc) Apply 

func (f RedirectPolicyFunc) Apply(req *http.Request, via []*http.Request) error

Apply calls f(req, via).

type Request 

type Request struct {
	URL        string
	Method     string
	QueryParam url.Values
	FormData   url.Values
	Header     http.Header
	UserInfo   *User
	Token      string
	Body       interface{}
	Result     interface{}
	Error      interface{}
	Time       time.Time
	RawRequest *http.Request
	// contains filtered or unexported fields
}

Request type is used to compose and send individual request from client go-resty is provide option override client level settings such as 

Auth Token, Basic Auth credentials, Header, Query Param, Form Data, Error object

and also you can add more options for that particular request

func R 

func R() *Request

R creates a new resty request object, it is used form a HTTP/RESTful request such as GET, POST, PUT, DELETE, HEAD, PATCH and OPTIONS.

func (*Request) Delete 

func (r *Request) Delete(url string) (*Response, error)

Delete method does DELETE HTTP request

func (*Request) Get 

func (r *Request) Get(url string) (*Response, error)

Get method does GET HTTP request

func (*Request) Head 

func (r *Request) Head(url string) (*Response, error)

Head method does HEAD HTTP request

func (*Request) Options 

func (r *Request) Options(url string) (*Response, error)

Options method does OPTIONS HTTP request

func (*Request) Patch 

func (r *Request) Patch(url string) (*Response, error)

Patch method does PATCH HTTP request

func (*Request) Post 

func (r *Request) Post(url string) (*Response, error)

Post method does POST HTTP request

func (*Request) Put 

func (r *Request) Put(url string) (*Response, error)

Put method does PUT HTTP request

func (*Request) SetAuthToken 

func (r *Request) SetAuthToken(token string) *Request

SetAuthToken method sets bearer auth token header in the current HTTP request. For Header exmaple: 

Authorization: Bearer <auth-token-value-comes-here>

For example: To set auth token BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F 

resty.R().SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")

This method overrides the Auth token set by method `resty.SetAuthToken`.

func (*Request) SetBasicAuth 

func (r *Request) SetBasicAuth(username, password string) *Request

SetBasicAuth method sets the basic authentication header in the current HTTP request. For Header example: 

Authorization: Basic <base64-encoded-value>

For example: To set the header for username "go-resty" and password "welcome" 

resty.R().SetBasicAuth("go-resty", "welcome")

This method overrides the credentials set by method `resty.SetBasicAuth`.

func (*Request) SetBody 

func (r *Request) SetBody(body interface{}) *Request

SetBody method sets the request body for the request. It supports various realtime need easy. We can say its quite handy or powerful. Supported request body data types is `string`, `[]byte`, `struct` and `map`. Body value can be pointer or non-pointer. Automatic marshalling for JSON and XML content type, if it is `struct` or `map`.

For Example:

Struct as a body input, based on content type, it will be marshalled. 

resty.R().
	SetBody(User{
		Username:"jeeva@myjeeva.com",
		Password:"welcome2resty",
	})

Map as a body input, based on content type, it will be marshalled. 

resty.R().
	SetBody(map[string]interface{}{
		"username":"jeeva@myjeeva.com",
		"password":"welcome2resty",
		"address":&Address{
			Address1:"1111 This is my street",
			Address2:"Apt 201",
			City:"My City",
			State:"My State",
			ZipCode:00000,
		},
	})

String as a body input. Suitable for any need as a string input. 

resty.R().
	SetBody(`{
		"username":"jeeva@getrightcare.com",
		"password":"admin"
	}`)

[]byte as a body input. Suitable for raw request such as file upload, serialize & deserialize, etc. 

resty.R().
	SetBody([]byte("This is my raw request, sent as-is"))

func (*Request) SetContentLength 

func (r *Request) SetContentLength(l bool) *Request

SetContentLength method sets the HTTP header `Content-Length` value for current request. By default go-resty won't set `Content-Length`. Also you have an option to enable for every request. See `resty.SetContentLength` 

resty.R().SetContentLength(true)

func (*Request) SetError 

func (r *Request) SetError(err interface{}) *Request

SetError method is to register the request `Error` object for automatic unmarshalling in the RESTful mode if response status code is greater than 399 and content type either JSON or XML.

Note: Error object can be pointer or non-pointer. 

resty.R().SetError(&AuthError{})
// OR
resty.R().SetError(AuthError{})

Accessing a error value 

response.Error().(*AuthError)

func (*Request) SetFile 

func (r *Request) SetFile(param, filePath string) *Request

SetFile method is to set single file field name and its path for multipart upload. 

resty.R().
	SetFile("my_file", "/Users/jeeva/Gas Bill - Sep.pdf")

func (*Request) SetFiles 

func (r *Request) SetFiles(files map[string]string) *Request

SetFiles method is to set multiple file field name and its path for multipart upload. 

resty.R().
	SetFiles(map[string]string{
			"my_file1": "/Users/jeeva/Gas Bill - Sep.pdf",
			"my_file2": "/Users/jeeva/Electricity Bill - Sep.pdf",
			"my_file3": "/Users/jeeva/Water Bill - Sep.pdf",
		})

func (*Request) SetFormData 

func (r *Request) SetFormData(data map[string]string) *Request

SetFormData method sets Form parameters and its values in the current request. It's applicable only HTTP method `POST` and `PUT` and requets content type would be set as `application/x-www-form-urlencoded`. 

resty.R().
	SetFormData(map[string]string{
		"access_token": "BC594900-518B-4F7E-AC75-BD37F019E08F",
		"user_id": "3455454545",
	})

Also you can override form data value, which was set at client instance level

func (*Request) SetHeader 

func (r *Request) SetHeader(header, value string) *Request

SetHeader method is to set a single header field and its value in the current request. For Example: To set `Content-Type` and `Accept` as `application/json`. 

resty.R().
	SetHeader("Content-Type", "application/json").
	SetHeader("Accept", "application/json")

Also you can override header value, which was set at client instance level.

func (*Request) SetHeaders 

func (r *Request) SetHeaders(headers map[string]string) *Request

SetHeaders method sets multiple headers field and its values at one go in the current request. For Example: To set `Content-Type` and `Accept` as `application/json` 

resty.R().
	SetHeaders(map[string]string{
		"Content-Type": "application/json",
		"Accept": "application/json",
	})

Also you can override header value, which was set at client instance level.

func (*Request) SetQueryParam 

func (r *Request) SetQueryParam(param, value string) *Request

SetQueryParam method sets single paramater and its value in the current request. It will be formed as query string for the request. For example: `search=kitchen%20papers&size=large` in the URL after `?` mark. 

resty.R().
	SetQueryParam("search", "kitchen papers").
	SetQueryParam("size", "large")

Also you can override query params value, which was set at client instance level

func (*Request) SetQueryParams 

func (r *Request) SetQueryParams(params map[string]string) *Request

SetQueryParams method sets multiple paramaters and its values at one go in the current request. It will be formed as query string for the request. For example: `search=kitchen%20papers&size=large` in the URL after `?` mark. 

resty.R().
	SetQueryParams(map[string]string{
		"search": "kitchen papers",
		"size": "large",
	})

Also you can override query params value, which was set at client instance level

func (*Request) SetResult 

func (r *Request) SetResult(res interface{}) *Request

SetResult method is to register the response `Result` object for automatic unmarshalling in the RESTful mode if response status code is between 200 and 299 and content type either JSON or XML.

Note: Result object can be pointer or non-pointer. 

resty.R().SetResult(&AuthToken{})
// OR
resty.R().SetResult(AuthToken{})

Accessing a result value 

response.Result().(*AuthToken)

type Response 

type Response struct {
	Body        []byte
	ReceivedAt  time.Time
	Request     *Request
	RawResponse *http.Response
}

Response is an object represents executed request and its values.

func (*Response) Cookies 

func (r *Response) Cookies() []*http.Cookie

Cookies method to access all the response cookies

func (*Response) Error 

func (r *Response) Error() interface{}

Error method returns the error object if it has one

func (*Response) Header 

func (r *Response) Header() http.Header

Header method returns the response headers

func (*Response) Result 

func (r *Response) Result() interface{}

Result method returns the response value as an object if it has one

func (*Response) Status 

func (r *Response) Status() string

Status method returns the HTTP status string for the executed request. 

For example: 200 OK

func (*Response) StatusCode 

func (r *Response) StatusCode() int

StatusCode method returns the HTTP status code for the executed request. 

For example: 200

func (*Response) String 

func (r *Response) String() string

String method returns the body of the server response as String.

func (*Response) Time 

func (r *Response) Time() time.Duration

Time method returns the time of HTTP response time that from request we sent and received a request. See `response.ReceivedAt` to know when client recevied response and see `response.Request.Time` to know when client sent a request.

type User 

type User struct {
	Username, Password string
}

User type is to hold an username and password information

Source Files

View all Source files

Jump to

Keyboard shortcuts

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