resty

func (*CircuitBreaker) SetFailureThreshold ¶

func (cb *CircuitBreaker) SetFailureThreshold(threshold uint32) *CircuitBreaker

SetFailureThreshold method sets the number of failures that must occur within the timeout duration for the CircuitBreaker to transition to the Open state.

func (*CircuitBreaker) SetPolicies ¶

func (cb *CircuitBreaker) SetPolicies(policies ...CircuitBreakerPolicy) *CircuitBreaker

SetPolicies method sets the one or more given CircuitBreakerPolicy(s) into CircuitBreaker, which will be used to determine whether a request is failed or successful by evaluating the response instance.

// set one policy
cb.SetPolicies(CircuitBreaker5xxPolicy)

// set multiple polices
cb.SetPolicies(policy1, policy2, policy3)

// if you have slice, do
cb.SetPolicies(policies...)

NOTE: This method overwrites the policies with the given new ones. See [CircuitBreaker.AddPolicies]

func (*CircuitBreaker) SetSuccessThreshold ¶

func (cb *CircuitBreaker) SetSuccessThreshold(threshold uint32) *CircuitBreaker

SetSuccessThreshold method sets the number of successes that must occur to transition the CircuitBreaker from the Half-Open state to the Closed state.

func (*CircuitBreaker) SetTimeout ¶

func (cb *CircuitBreaker) SetTimeout(timeout time.Duration) *CircuitBreaker

SetTimeout method sets the timeout duration for the CircuitBreaker. When the timeout reaches, a single request is allowed to determine the state.

func (*Client) AddContentDecompresser ¶

func (c *Client) AddContentDecompresser(k string, d ContentDecompresser) *Client

AddContentDecompresser method adds the user-provided Content-Encoding (RFC 9110) Decompresser and directive into a client.

NOTE: It overwrites the Decompresser function if the given Content-Encoding directive already exists.

func (*Client) AddContentTypeDecoder ¶

func (c *Client) AddContentTypeDecoder(ct string, d ContentTypeDecoder) *Client

AddContentTypeDecoder method adds the user-provided Content-Type decoder into a client.

NOTE: It overwrites the decoder function if the given Content-Type key already exists.

func (*Client) AddContentTypeEncoder ¶

func (c *Client) AddContentTypeEncoder(ct string, e ContentTypeEncoder) *Client

AddContentTypeEncoder method adds the user-provided Content-Type encoder into a client.

NOTE: It overwrites the encoder function if the given Content-Type key already exists.

func (*Client) AddRequestMiddleware ¶

func (c *Client) AddRequestMiddleware(m RequestMiddleware) *Client

AddRequestMiddleware method appends a request middleware to the before request chain. After all requests, middlewares are applied, and the request is sent to the host server.

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

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

func (*Client) AddResponseMiddleware ¶

func (c *Client) AddResponseMiddleware(m ResponseMiddleware) *Client

AddResponseMiddleware method appends response middleware to the after-response chain. All the response middlewares are applied; once we receive a response from the host server.

client.AddResponseMiddleware(func(c *resty.Client, r *resty.Response) error {
	// Now you have access to the Client and Response instance
	// Also, you could access request via Response.Request i.e., r.Request
	// manipulate it as per your need

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

func (*Client) AddRetryConditions ¶

func (c *Client) AddRetryConditions(conditions ...RetryConditionFunc) *Client

AddRetryConditions method adds one or more retry condition functions into the request. These retry conditions are executed to determine if the request can be retried. The request will retry if any functions return `true`, otherwise return `false`.

NOTE:

• The default retry conditions are applied first.
• The client-level retry conditions are applied to all requests.
• The request-level retry conditions are executed first before the client-level retry conditions. See Request.AddRetryConditions, Request.SetRetryConditions

func (*Client) AddRetryHooks ¶

func (c *Client) AddRetryHooks(hooks ...RetryHookFunc) *Client

AddRetryHooks method adds one or more side-effecting retry hooks to an array of hooks that will be executed on each retry.

NOTE:

• All the retry hooks are executed on request retry.
• The request-level retry hooks are executed first before client-level hooks.

func (*Client) AllowMethodDeletePayload ¶

func (c *Client) AllowMethodDeletePayload() bool

AllowMethodDeletePayload method returns `true` if the client is enabled to allow payload with DELETE method; otherwise, it is `false`.

More info, refer to GH#881

func (*Client) AllowMethodGetPayload ¶

func (c *Client) AllowMethodGetPayload() bool

AllowMethodGetPayload method returns `true` if the client is enabled to allow payload with GET method; otherwise, it is `false`.

func (*Client) AllowNonIdempotentRetry ¶

func (c *Client) AllowNonIdempotentRetry() bool

AllowNonIdempotentRetry method returns true if the client is enabled to allow non-idempotent HTTP methods retry; otherwise, it is `false`

Default value is `false`

func (*Client) AuthScheme ¶

func (c *Client) AuthScheme() string

AuthScheme method returns the auth scheme name set in the client instance.

See Client.SetAuthScheme, Request.SetAuthScheme.

func (*Client) AuthToken ¶

func (c *Client) AuthToken() string

AuthToken method returns the auth token value registered in the client instance.

func (*Client) BaseURL ¶

func (c *Client) BaseURL() string

BaseURL method returns the Base URL value from the client instance.

func (*Client) Client ¶

func (c *Client) Client() *http.Client

Client method returns the underlying Go http.Client used by the Resty.

func (*Client) Clone ¶

func (c *Client) Clone(ctx context.Context) *Client

Clone method returns a clone of the original client.

NOTE: Use with care:

• Interface values are not deeply cloned. Thus, both the original and the clone will use the same value.
• It is not safe for concurrent use. You should only use this method when you are sure that any other concurrent process is not using the client or client instance is protected by a mutex.

func (*Client) Close ¶

func (c *Client) Close() error

Close method performs cleanup and closure activities on the client instance

func (*Client) ContentDecompresserKeys ¶

func (c *Client) ContentDecompresserKeys() string

ContentDecompresserKeys method returns all the registered content-encoding Decompressers keys as comma-separated string.

func (*Client) ContentDecompressers ¶

func (c *Client) ContentDecompressers() map[string]ContentDecompresser

ContentDecompressers method returns all the registered content-encoding Decompressers.

func (*Client) ContentTypeDecoders ¶

func (c *Client) ContentTypeDecoders() map[string]ContentTypeDecoder

ContentTypeDecoders method returns all the registered content type decoders.

func (*Client) ContentTypeEncoders ¶

func (c *Client) ContentTypeEncoders() map[string]ContentTypeEncoder

ContentTypeEncoders method returns all the registered content type encoders.

func (*Client) Context ¶

func (c *Client) Context() context.Context

Context method returns the context.Context from the client instance.

func (*Client) CookieJar ¶

func (c *Client) CookieJar() http.CookieJar

CookieJar method returns the HTTP cookie jar instance from the underlying Go HTTP Client.

func (*Client) Cookies ¶

func (c *Client) Cookies() []*http.Cookie

Cookies method returns all cookies registered in the client instance.

func (*Client) DebugBodyLimit ¶

func (c *Client) DebugBodyLimit() int

DebugBodyLimit method returns the debug body limit value set on the client instance

func (*Client) DisableDebug ¶

func (c *Client) DisableDebug() *Client

DisableDebug method is a helper method for Client.SetDebug

func (*Client) DisableGenerateCurlCmd ¶

func (c *Client) DisableGenerateCurlCmd() *Client

DisableGenerateCurlCmd method disables the option set by Client.EnableGenerateCurlCmd or Client.SetGenerateCurlCmd.

func (*Client) DisableRetryDefaultConditions ¶

func (c *Client) DisableRetryDefaultConditions() *Client

DisableRetryDefaultConditions method disables the Resty's default retry conditions

func (*Client) DisableTrace ¶

func (c *Client) DisableTrace() *Client

DisableTrace method disables the Resty client trace. Refer to Client.EnableTrace.

func (*Client) EnableDebug ¶

func (c *Client) EnableDebug() *Client

EnableDebug method is a helper method for Client.SetDebug

func (*Client) EnableGenerateCurlCmd ¶

func (c *Client) EnableGenerateCurlCmd() *Client

EnableGenerateCurlCmd method enables the generation of curl command at the client instance level.

By default, Resty does not log the curl command in the debug log since it has the potential to leak sensitive data unless explicitly enabled via Client.SetDebugLogCurlCmd or Request.SetDebugLogCurlCmd.

NOTE: Use with care.

• Potential to leak sensitive data from Request and Response in the debug log when the debug log option is enabled.
• Additional memory usage since the request body was reread.
• curl body is not generated for io.Reader and multipart request flow.

func (*Client) EnableRetryDefaultConditions ¶

func (c *Client) EnableRetryDefaultConditions() *Client

EnableRetryDefaultConditions method enables the Resty's default retry conditions

func (*Client) EnableTrace ¶

func (c *Client) EnableTrace() *Client

EnableTrace method enables the Resty client trace for the requests fired from the client using httptrace.ClientTrace and provides insights.

client := resty.New().EnableTrace()

resp, err := client.R().Get("https://httpbin.org/get")
fmt.Println("error:", err)
fmt.Println("Trace Info:", resp.Request.TraceInfo())

The method Request.EnableTrace is also available to get trace info for a single request.

func (*Client) Error ¶

func (c *Client) Error() reflect.Type

Error method returns the global or client common `Error` object type registered in the Resty.

func (*Client) FormData ¶

func (c *Client) FormData() url.Values

FormData method returns the form parameters and their values from the client instance.

func (*Client) HTTPTransport ¶

func (c *Client) HTTPTransport() (*http.Transport, error)

HTTPTransport method does type assertion and returns http.Transport from the client instance, if type assertion fails it returns an error

func (*Client) Header ¶

func (c *Client) Header() http.Header

Header method returns the headers from the client instance.

func (*Client) HeaderAuthorizationKey ¶

func (c *Client) HeaderAuthorizationKey() string

HeaderAuthorizationKey method returns the HTTP header name for Authorization from the client instance.

func (*Client) IsContentLength ¶

func (c *Client) IsContentLength() bool

IsContentLength method returns true if the user requests to set content length. Otherwise, it is false.

func (*Client) IsDebug ¶

func (c *Client) IsDebug() bool

IsDebug method returns `true` if the client is in debug mode; otherwise, it is `false`.

func (*Client) IsDisableWarn ¶

func (c *Client) IsDisableWarn() bool

IsDisableWarn method returns `true` if the warning message is disabled; otherwise, it is `false`.

func (*Client) IsProxySet ¶

func (c *Client) IsProxySet() bool

IsProxySet method returns the true is proxy is set from the Resty client; otherwise false. By default, the proxy is set from the environment variable; refer to http.ProxyFromEnvironment.

func (*Client) IsRetryDefaultConditions ¶

func (c *Client) IsRetryDefaultConditions() bool

IsRetryDefaultConditions method returns true if Resty's default retry conditions are enabled otherwise false

Default value is `true`

func (*Client) IsSaveResponse ¶

func (c *Client) IsSaveResponse() bool

IsSaveResponse method returns true if the save response is set to true; otherwise, false

func (*Client) IsTrace ¶

func (c *Client) IsTrace() bool

IsTrace method returns true if the trace is enabled on the client instance; otherwise, it returns false.

func (*Client) LoadBalancer ¶

func (c *Client) LoadBalancer() LoadBalancer

LoadBalancer method returns the request load balancer instance from the client instance. Otherwise returns nil.

func (*Client) Logger ¶

func (c *Client) Logger() Logger

Logger method returns the logger instance used by the client instance.

func (*Client) NewRequest ¶

func (c *Client) NewRequest() *Request

NewRequest method is an alias for method `R()`.

func (*Client) OnDebugLog ¶

func (c *Client) OnDebugLog(dlc DebugLogCallbackFunc) *Client

OnDebugLog method sets the debug log callback function to the client instance. Registered callback gets called before the Resty logs the information.

func (*Client) OnError ¶

func (c *Client) OnError(h ErrorHook) *Client

OnError method adds a callback that will be run whenever a request execution fails. This is called after all retries have been attempted (if any). If there was a response from the server, the error will be wrapped in ResponseError which has the last response received from the server.

client.OnError(func(req *resty.Request, err error) {
	if v, ok := err.(*resty.ResponseError); ok {
		// Do something with v.Response
	}
	// Log the error, increment a metric, etc...
})

Out of the Client.OnSuccess, Client.OnError, Client.OnInvalid, Client.OnPanic callbacks, exactly one set will be invoked for each call to Request.Execute that completes.

NOTE:

• Do not use Client setter methods within OnError hooks; deadlock will happen.

func (*Client) OnInvalid ¶

func (c *Client) OnInvalid(h ErrorHook) *Client

OnInvalid method adds a callback that will be run whenever a request execution fails before it starts because the request is invalid.

Out of the Client.OnSuccess, Client.OnError, Client.OnInvalid, Client.OnPanic callbacks, exactly one set will be invoked for each call to Request.Execute that completes.

NOTE:

• Do not use Client setter methods within OnInvalid hooks; deadlock will happen.

func (*Client) OnPanic ¶

func (c *Client) OnPanic(h ErrorHook) *Client

OnPanic method adds a callback that will be run whenever a request execution panics.

Out of the Client.OnSuccess, Client.OnError, Client.OnInvalid, Client.OnPanic callbacks, exactly one set will be invoked for each call to Request.Execute that completes.

If an Client.OnSuccess, Client.OnError, or Client.OnInvalid callback panics, then exactly one rule can be violated.

NOTE:

• Do not use Client setter methods within OnPanic hooks; deadlock will happen.

func (*Client) OnSuccess ¶

func (c *Client) OnSuccess(h SuccessHook) *Client

OnSuccess method adds a callback that will be run whenever a request execution succeeds. This is called after all retries have been attempted (if any).

Out of the Client.OnSuccess, Client.OnError, Client.OnInvalid, Client.OnPanic callbacks, exactly one set will be invoked for each call to Request.Execute that completes.

NOTE:

• Do not use Client setter methods within OnSuccess hooks; deadlock will happen.

func (*Client) OutputDirectory ¶

func (c *Client) OutputDirectory() string

OutputDirectory method returns the output directory value from the client.

func (*Client) PathParams ¶

func (c *Client) PathParams() map[string]string

PathParams method returns the path parameters from the client.

pathParams := client.PathParams()

func (*Client) ProxyURL ¶

func (c *Client) ProxyURL() *url.URL

ProxyURL method returns the proxy URL if set otherwise nil.

func (*Client) QueryParams ¶

func (c *Client) QueryParams() url.Values

QueryParams method returns all query parameters and their values from the client instance.

func (*Client) R ¶

func (c *Client) R() *Request

R method creates a new request instance; it's used for Get, Post, Put, Delete, Patch, Head, Options, etc.

func (*Client) RemoveProxy ¶

func (c *Client) RemoveProxy() *Client

RemoveProxy method removes the proxy configuration from the Resty client

client.RemoveProxy()

func (*Client) ResponseBodyLimit ¶

func (c *Client) ResponseBodyLimit() int64

ResponseBodyLimit method returns the value max body size limit in bytes from the client instance.

func (*Client) ResponseBodyUnlimitedReads ¶

func (c *Client) ResponseBodyUnlimitedReads() bool

ResponseBodyUnlimitedReads method returns true if enabled. Otherwise, it returns false

func (*Client) RetryConditions ¶

func (c *Client) RetryConditions() []RetryConditionFunc

RetryConditions method returns all the retry condition functions.

func (*Client) RetryCount ¶

func (c *Client) RetryCount() int

RetryCount method returns the retry count value from the client instance.

func (*Client) RetryHooks ¶

func (c *Client) RetryHooks() []RetryHookFunc

RetryHooks method returns all the retry hook functions.

func (*Client) RetryMaxWaitTime ¶

func (c *Client) RetryMaxWaitTime() time.Duration

RetryMaxWaitTime method returns the retry max wait time that is used to sleep before retrying the request.

func (*Client) RetryStrategy ¶

func (c *Client) RetryStrategy() RetryStrategyFunc

RetryStrategy method returns the retry strategy function; otherwise, it is nil.

See Client.SetRetryStrategy

func (*Client) RetryWaitTime ¶

func (c *Client) RetryWaitTime() time.Duration

RetryWaitTime method returns the retry wait time that is used to sleep before retrying the request.

func (*Client) Scheme ¶

func (c *Client) Scheme() string

Scheme method returns custom scheme value from the client.

scheme := client.Scheme()

func (*Client) SetAllowMethodDeletePayload ¶

func (c *Client) SetAllowMethodDeletePayload(allow bool) *Client

SetAllowMethodDeletePayload method allows the DELETE method with payload on the Resty client. By default, Resty does not allow.

client.SetAllowMethodDeletePayload(true)

More info, refer to GH#881

It can be overridden at the request level. See Request.SetAllowMethodDeletePayload

func (*Client) SetAllowMethodGetPayload ¶

func (c *Client) SetAllowMethodGetPayload(allow bool) *Client

SetAllowMethodGetPayload method allows the GET method with payload on the Resty client. By default, Resty does not allow.

client.SetAllowMethodGetPayload(true)

It can be overridden at the request level. See Request.SetAllowMethodGetPayload

func (*Client) SetAllowNonIdempotentRetry ¶

func (c *Client) SetAllowNonIdempotentRetry(b bool) *Client

SetAllowNonIdempotentRetry method is used to enable/disable non-idempotent HTTP methods retry. By default, Resty only allows idempotent HTTP methods, see RFC 9110 Section 9.2.2, RFC 9110 Section 18.2

It can be overridden at request level, see Request.SetAllowNonIdempotentRetry

func (*Client) SetAuthScheme ¶

func (c *Client) SetAuthScheme(scheme string) *Client

SetAuthScheme method sets the auth scheme type in the HTTP request. For Example:

Authorization: <auth-scheme-value> <auth-token-value>

For Example: To set the scheme to use OAuth

client.SetAuthScheme("OAuth")

This auth scheme gets added to all the requests raised from this client instance. Also, it can be overridden at the request level.

Information about auth schemes can be found in RFC 7235, IANA HTTP Auth schemes.

See Request.SetAuthScheme.

func (*Client) SetAuthToken ¶

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

SetAuthToken method sets the auth token of the `Authorization` header for all HTTP requests. The default auth scheme is `Bearer`; it can be customized with the method Client.SetAuthScheme. For Example:

Authorization: <auth-scheme> <auth-token-value>

For Example: To set auth token BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F

client.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")

This auth token gets added to all the requests raised from this client instance. Also, it can be overridden at the request level.

See Request.SetAuthToken.

func (*Client) SetBaseURL ¶

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

SetBaseURL method sets the Base URL in the client instance. It will be used with a request raised from this client with a relative URL

// Setting HTTP address
client.SetBaseURL("http://myjeeva.com")

// Setting HTTPS address
client.SetBaseURL("https://myjeeva.com")

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"

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

This basic auth information is added to all requests from this client instance. It can also be overridden at the request level.

See Request.SetBasicAuth.

func (*Client) SetCertificateFromFile ¶

func (c *Client) SetCertificateFromFile(certFilePath, certKeyFilePath string) *Client

SetCertificateFromFile method helps to set client certificates into Resty from cert and key files to perform SSL client authentication

client.SetCertificateFromFile("certs/client.pem", "certs/client.key")

func (*Client) SetCertificateFromString ¶

func (c *Client) SetCertificateFromString(certStr, certKeyStr string) *Client

SetCertificateFromString method helps to set client certificates into Resty from string to perform SSL client authentication

myClientCertStr := `-----BEGIN CERTIFICATE-----
... cert content ...
-----END CERTIFICATE-----`

myClientCertKeyStr := `-----BEGIN PRIVATE KEY-----
... cert key content ...
-----END PRIVATE KEY-----`

client.SetCertificateFromString(myClientCertStr, myClientCertKeyStr)

func (*Client) SetCertificates ¶

func (c *Client) SetCertificates(certs ...tls.Certificate) *Client

SetCertificates method helps to conveniently set a slice of client certificates into Resty to perform SSL client authentication

cert, err := tls.LoadX509KeyPair("certs/client.pem", "certs/client.key")
if err != nil {
	log.Printf("ERROR client certificate/key parsing error: %v", err)
	return
}

client.SetCertificates(cert)

func (*Client) SetCircuitBreaker ¶

func (c *Client) SetCircuitBreaker(b *CircuitBreaker) *Client

SetCircuitBreaker method sets the Circuit Breaker instance into the client. It is used to prevent the client from sending requests that are likely to fail. For Example: To use the default Circuit Breaker:

client.SetCircuitBreaker(NewCircuitBreaker())

func (*Client) SetClientRootCertificateFromString ¶

func (c *Client) SetClientRootCertificateFromString(pemCerts string) *Client

SetClientRootCertificateFromString method helps to add a client root certificate from the string into the Resty client

myClientRootCertStr := `-----BEGIN CERTIFICATE-----
... cert content ...
-----END CERTIFICATE-----`

client.SetClientRootCertificateFromString(myClientRootCertStr)

func (*Client) SetClientRootCertificates ¶

func (c *Client) SetClientRootCertificates(pemFilePaths ...string) *Client

SetClientRootCertificates method helps to add one or more client root certificate files into the Resty client

// one pem file path
client.SetClientRootCertificates("/path/to/client-root/pemFile.pem")

// one or more pem file path(s)
client.SetClientRootCertificates(
    "/path/to/client-root/pemFile1.pem",
    "/path/to/client-root/pemFile2.pem"
    "/path/to/client-root/pemFile3.pem"
)

// if you happen to have string slices
client.SetClientRootCertificates(certs...)

func (*Client) SetClientRootCertificatesWatcher ¶

func (c *Client) SetClientRootCertificatesWatcher(options *CertWatcherOptions, pemFilePaths ...string) *Client

SetClientRootCertificatesWatcher method enables dynamic reloading of one or more client root certificate files. It is designed for scenarios involving long-running Resty clients where certificates may be renewed.

client.SetClientRootCertificatesWatcher(
	&resty.CertWatcherOptions{
		PoolInterval: 24 * time.Hour,
	},
	"client-root-ca.pem",
)

func (*Client) SetCloseConnection ¶

func (c *Client) SetCloseConnection(close bool) *Client

SetCloseConnection method sets variable `Close` in HTTP request struct with the given value. More info: https://golang.org/src/net/http/request.go

It can be overridden at the request level, see Request.SetCloseConnection

func (*Client) SetContentDecompresserKeys ¶

func (c *Client) SetContentDecompresserKeys(keys []string) *Client

SetContentDecompresserKeys method sets given Content-Encoding (RFC 9110) directives into the client instance.

It checks the given Content-Encoding exists in the ContentDecompresser list before assigning it, if it does not exist, it will skip that directive.

Use this method to overwrite the default order. If a new content Decompresser is added, that directive will be the first.

func (*Client) SetContentLength ¶

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

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

client.SetContentLength(true)

Also, you have the option to enable a particular request. See Request.SetContentLength

func (*Client) SetContext ¶

func (c *Client) SetContext(ctx context.Context) *Client

SetContext method sets the given context.Context in the client instance and it gets added to Request raised from this instance.

func (*Client) SetCookie ¶

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

SetCookie method appends a single cookie to the client instance. These cookies will be added to all the requests from this client instance.

client.SetCookie(&http.Cookie{
	Name:"go-resty",
	Value:"This is cookie value",
})

func (*Client) SetCookieJar ¶

func (c *Client) SetCookieJar(jar http.CookieJar) *Client

SetCookieJar method sets custom http.CookieJar in the resty client. It's a way to override the default.

For Example, sometimes we don't want to save cookies in API mode so that we can remove the default CookieJar in resty client.

client.SetCookieJar(nil)

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 requests from this client instance.

cookies := []*http.Cookie{
	&http.Cookie{
		Name:"go-resty-1",
		Value:"This is cookie 1 value",
	},
	&http.Cookie{
		Name:"go-resty-2",
		Value:"This is cookie 2 value",
	},
}

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

func (*Client) SetDebug ¶

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

SetDebug method enables the debug mode on the Resty client. The client logs details of every request and response.

client.SetDebug(true)
// OR
client.EnableDebug()

Also, it can be enabled at the request level for a particular request; see Request.SetDebug.

• For Request, it logs information such as HTTP verb, Relative URL path, Host, Headers, and Body if it has one.
• For Response, it logs information such as Status, Response Time, Headers, and Body if it has one.

func (*Client) SetDebugBodyLimit ¶

func (c *Client) SetDebugBodyLimit(sl int) *Client

SetDebugBodyLimit sets the maximum size in bytes for which the response and request body will be logged in debug mode.

client.SetDebugBodyLimit(1000000)

func (*Client) SetDebugLogCurlCmd ¶

func (c *Client) SetDebugLogCurlCmd(b bool) *Client

SetDebugLogCurlCmd method enables the curl command to be logged in the debug log.

It can be overridden at the request level; see Request.SetDebugLogCurlCmd

func (*Client) SetDebugLogFormatter ¶

func (c *Client) SetDebugLogFormatter(df DebugLogFormatterFunc) *Client

SetDebugLogFormatter method sets the Resty debug log formatter to the client instance.

func (*Client) SetDigestAuth ¶

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

SetDigestAuth method sets the Digest Auth transport with provided credentials in the client. If a server responds with 401 and sends a Digest challenge in the header `WWW-Authenticate`, the request will be resent with the appropriate digest `Authorization` header.

For Example: To set the Digest scheme with user "Mufasa" and password "Circle Of Life"

client.SetDigestAuth("Mufasa", "Circle Of Life")

Information about Digest Access Authentication can be found in RFC 7616.

NOTE:

• On the QOP `auth-int` scenario, the request body is read into memory to compute the body hash that increases memory usage.
• Create a dedicated client instance to use digest auth, as it does digest auth for all the requests raised by the client.

func (*Client) SetDisableWarn ¶

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

SetDisableWarn method disables the warning log message on the Resty client.

For example, Resty warns users when BasicAuth is used in non-TLS mode.

client.SetDisableWarn(true)

func (*Client) SetDoNotParseResponse ¶

func (c *Client) SetDoNotParseResponse(notParse bool) *Client

SetDoNotParseResponse method instructs Resty not to parse the response body automatically.

Resty exposes the raw response body as io.ReadCloser. If you use it, do not forget to close the body, otherwise, you might get into connection leaks, and connection reuse may not happen.

NOTE: The default Response middlewares are not executed when using this option. User takes over the control of handling response body from Resty.

func (*Client) SetError ¶

func (c *Client) SetError(v any) *Client

SetError method registers the global or client common `Error` object into Resty. It is used for automatic unmarshalling if the response status code is greater than 399 and content type is JSON or XML. It can be a pointer or a non-pointer.

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

func (*Client) SetFormData ¶

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

SetFormData method sets Form parameters and their values in the client instance. The request content type would be set as `application/x-www-form-urlencoded`. The client-level form data gets added to all the requests. Also, it can be overridden at the request level.

See Request.SetFormData.

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

func (*Client) SetGenerateCurlCmd ¶

func (c *Client) SetGenerateCurlCmd(b bool) *Client

SetGenerateCurlCmd method is used to turn on/off the generate curl command at the client instance level.

By default, Resty does not log the curl command in the debug log since it has the potential to leak sensitive data unless explicitly enabled via Client.SetDebugLogCurlCmd or Request.SetDebugLogCurlCmd.

NOTE: Use with care.

• Potential to leak sensitive data from Request and Response in the debug log when the debug log option is enabled.
• Additional memory usage since the request body was reread.
• curl body is not generated for io.Reader and multipart request flow.

It can be overridden at the request level; see Request.SetGenerateCurlCmd

func (*Client) SetHeader ¶

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

SetHeader method sets a single header and its value in the client instance. These headers will be applied to all requests raised from the client instance. Also, it can be overridden by request-level header options.

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

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

See Request.SetHeader or Request.SetHeaders.

func (*Client) SetHeaderAuthorizationKey ¶

func (c *Client) SetHeaderAuthorizationKey(k string) *Client

SetHeaderAuthorizationKey method sets the given HTTP header name for Authorization in the client instance.

It can be overridden at the request level; see Request.SetHeaderAuthorizationKey.

client.SetHeaderAuthorizationKey("X-Custom-Authorization")

func (*Client) SetHeaderVerbatim ¶

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

SetHeaderVerbatim method is used to set the HTTP header key and value verbatim in the current request. It is typically helpful for legacy applications or servers that require HTTP headers in a certain way

For Example: To set header key as `all_lowercase`, `UPPERCASE`, and `x-cloud-trace-id`

client.
	SetHeaderVerbatim("all_lowercase", "available").
	SetHeaderVerbatim("UPPERCASE", "available").
	SetHeaderVerbatim("x-cloud-trace-id", "798e94019e5fc4d57fbb8901eb4c6cae")

See Request.SetHeaderVerbatim.

func (*Client) SetHeaders ¶

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

SetHeaders method sets multiple headers and their values at one go, and these headers will be applied to all requests raised from the client instance. Also, it can be overridden at request-level headers options.

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

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

See Request.SetHeaders or Request.SetHeader.

func (*Client) SetJSONEscapeHTML ¶

func (c *Client) SetJSONEscapeHTML(b bool) *Client

SetJSONEscapeHTML method enables or disables the HTML escape on JSON marshal. By default, escape HTML is `true`.

NOTE: This option only applies to the standard JSON Marshaller used by Resty.

It can be overridden at the request level, see Request.SetJSONEscapeHTML

func (*Client) SetLoadBalancer ¶

func (c *Client) SetLoadBalancer(b LoadBalancer) *Client

SetLoadBalancer method is used to set the new request load balancer into the client.

func (*Client) SetLogger ¶

func (c *Client) SetLogger(l Logger) *Client

SetLogger method sets given writer for logging Resty request and response details.

Compliant to interface resty.Logger

func (*Client) SetOutputDirectory ¶

func (c *Client) SetOutputDirectory(dirPath string) *Client

SetOutputDirectory method sets the output directory for saving HTTP responses in a file. Resty creates one if the output directory does not exist. This setting is optional, if you plan to use the absolute path in Request.SetOutputFileName and can used together.

client.SetOutputDirectory("/save/http/response/here")

func (*Client) SetPathParam ¶

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

SetPathParam method sets a single URL path key-value pair in the Resty client instance.

client.SetPathParam("userId", "[email protected]")

Result:
   URL - /v1/users/{userId}/details
   Composed URL - /v1/users/[email protected]/details

It replaces the value of the key while composing the request URL. The value will be escaped using url.PathEscape function.

It can be overridden at the request level, see Request.SetPathParam or Request.SetPathParams

func (*Client) SetPathParams ¶

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

SetPathParams method sets multiple URL path key-value pairs at one go in the Resty client instance.

client.SetPathParams(map[string]string{
	"userId":       "[email protected]",
	"subAccountId": "100002",
	"path":         "groups/developers",
})

Result:
   URL - /v1/users/{userId}/{subAccountId}/{path}/details
   Composed URL - /v1/users/[email protected]/100002/groups%2Fdevelopers/details

It replaces the value of the key while composing the request URL. The values will be escaped using url.PathEscape function.

It can be overridden at the request level, see Request.SetPathParam or Request.SetPathParams

func (*Client) SetProxy ¶

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

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

// HTTP/HTTPS proxy
client.SetProxy("http://proxyserver:8888")

// SOCKS5 Proxy
client.SetProxy("socks5://127.0.0.1:1080")

OR you could also set Proxy via environment variable, refer to http.ProxyFromEnvironment

func (*Client) SetQueryParam ¶

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

SetQueryParam method sets a single parameter and its value in the client instance. It will be formed as a query string for the request.

For Example: `search=kitchen%20papers&size=large`

In the URL after the `?` mark. These query params will be added to all the requests raised from this client instance. Also, it can be overridden at the request level.

See Request.SetQueryParam or Request.SetQueryParams.

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

func (*Client) SetQueryParams ¶

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

SetQueryParams method sets multiple parameters and their values at one go in the client instance. It will be formed as a query string for the request.

For Example: `search=kitchen%20papers&size=large`

In the URL after the `?` mark. These query params will be added to all the requests raised from this client instance. Also, it can be overridden at the request level.

See Request.SetQueryParams or Request.SetQueryParam.

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

func (*Client) SetRawPathParam ¶

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

SetRawPathParam method sets a single URL path key-value pair in the Resty client instance without path escape.

client.SetRawPathParam("path", "groups/developers")

Result:
	URL - /v1/users/{path}/details
	Composed URL - /v1/users/groups/developers/details

It replaces the value of the key while composing the request URL. The value will be used as-is, no path escape applied.

It can be overridden at the request level, see Request.SetRawPathParam or Request.SetRawPathParams

func (*Client) SetRawPathParams ¶

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

SetRawPathParams method sets multiple URL path key-value pairs at one go in the Resty client instance without path escape.

client.SetRawPathParams(map[string]string{
	"userId":       "[email protected]",
	"subAccountId": "100002",
	"path":         "groups/developers",
})

Result:
   URL - /v1/users/{userId}/{subAccountId}/{path}/details
   Composed URL - /v1/users/[email protected]/100002/groups/developers/details

It replaces the value of the key while composing the request URL. The value will be used as-is, no path escape applied.

It can be overridden at the request level, see Request.SetRawPathParam or Request.SetRawPathParams

func (*Client) SetRedirectPolicy ¶

func (c *Client) SetRedirectPolicy(policies ...RedirectPolicy) *Client

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

client.SetRedirectPolicy(resty.FlexibleRedirectPolicy(20))

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

NOTE: It overwrites the previous redirect policies in the client instance.

func (*Client) SetRequestMiddlewares ¶

func (c *Client) SetRequestMiddlewares(middlewares ...RequestMiddleware) *Client

SetRequestMiddlewares method allows Resty users to override the default request middlewares sequence

client.SetRequestMiddlewares(
	Custom1RequestMiddleware,
	Custom2RequestMiddleware,
	resty.PrepareRequestMiddleware, // after this, `Request.RawRequest` instance is available
	Custom3RequestMiddleware,
	Custom4RequestMiddleware,
)

See, Client.AddRequestMiddleware

NOTE:

• It overwrites the existing request middleware list.
• Be sure to include Resty request middlewares in the request chain at the appropriate spot.

func (*Client) SetResponseBodyLimit ¶

func (c *Client) SetResponseBodyLimit(v int64) *Client

SetResponseBodyLimit method sets a maximum body size limit in bytes on response, avoid reading too much data to memory.

Client will return resty.ErrResponseBodyTooLarge if the body size of the body in the uncompressed response is larger than the limit. Body size limit will not be enforced in the following cases:

• ResponseBodyLimit <= 0, which is the default behavior.
• Request.SetOutputFileName is called to save response data to the file.
• "DoNotParseResponse" is set for client or request.

It can be overridden at the request level; see Request.SetResponseBodyLimit

func (*Client) SetResponseBodyUnlimitedReads ¶

func (c *Client) SetResponseBodyUnlimitedReads(b bool) *Client

SetResponseBodyUnlimitedReads method is to turn on/off the response body in memory that provides an ability to do unlimited reads.

It can be overridden at the request level; see Request.SetResponseBodyUnlimitedReads

Unlimited reads are possible in a few scenarios, even without enabling it.

• When debug mode is enabled

NOTE: Use with care

• Turning on this feature keeps the response body in memory, which might cause additional memory usage.

func (*Client) SetResponseMiddlewares ¶

func (c *Client) SetResponseMiddlewares(middlewares ...ResponseMiddleware) *Client

SetResponseMiddlewares method allows Resty users to override the default response middlewares sequence

client.SetResponseMiddlewares(
	Custom1ResponseMiddleware,
	Custom2ResponseMiddleware,
	resty.AutoParseResponseMiddleware, // before this, the body is not read except on the debug flow
	Custom3ResponseMiddleware,
	resty.SaveToFileResponseMiddleware, // See, Request.SetOutputFileName, Request.SetSaveResponse
	Custom4ResponseMiddleware,
	Custom5ResponseMiddleware,
)

See, Client.AddResponseMiddleware

NOTE:

• It overwrites the existing response middleware list.
• Be sure to include Resty response middlewares in the response chain at the appropriate spot.

func (*Client) SetRetryCount ¶

func (c *Client) SetRetryCount(count int) *Client

SetRetryCount method enables retry on Resty client and allows you to set no. of retry count.

first attempt + retry count = total attempts

See Request.SetRetryStrategy

NOTE:

• By default, Resty only does retry on idempotent HTTP verb, RFC 9110 Section 9.2.2, RFC 9110 Section 18.2

func (*Client) SetRetryDefaultConditions ¶

func (c *Client) SetRetryDefaultConditions(b bool) *Client

SetRetryDefaultConditions method is used to enable/disable the Resty's default retry conditions

It can be overridden at request level, see Request.SetRetryDefaultConditions

func (*Client) SetRetryMaxWaitTime ¶

func (c *Client) SetRetryMaxWaitTime(maxWaitTime time.Duration) *Client

SetRetryMaxWaitTime method sets the max wait time for sleep before retrying

Default is 2 seconds.

func (*Client) SetRetryStrategy ¶

func (c *Client) SetRetryStrategy(rs RetryStrategyFunc) *Client

SetRetryStrategy method used to set the custom Retry strategy into Resty client, it is used to get wait time before each retry. It can be overridden at request level, see Request.SetRetryStrategy

Default (nil) implies exponential backoff with a jitter strategy

func (*Client) SetRetryWaitTime ¶

func (c *Client) SetRetryWaitTime(waitTime time.Duration) *Client

SetRetryWaitTime method sets the default wait time for sleep before retrying

Default is 100 milliseconds.

func (*Client) SetRootCertificateFromString ¶

func (c *Client) SetRootCertificateFromString(pemCerts string) *Client

SetRootCertificateFromString method helps to add root certificate from the string into the Resty client

myRootCertStr := `-----BEGIN CERTIFICATE-----
... cert content ...
-----END CERTIFICATE-----`

client.SetRootCertificateFromString(myRootCertStr)

func (*Client) SetRootCertificates ¶

func (c *Client) SetRootCertificates(pemFilePaths ...string) *Client

SetRootCertificates method helps to add one or more root certificate files into the Resty client

// one pem file path
client.SetRootCertificates("/path/to/root/pemFile.pem")

// one or more pem file path(s)
client.SetRootCertificates(
    "/path/to/root/pemFile1.pem",
    "/path/to/root/pemFile2.pem"
    "/path/to/root/pemFile3.pem"
)

// if you happen to have string slices
client.SetRootCertificates(certs...)

func (*Client) SetRootCertificatesWatcher ¶

func (c *Client) SetRootCertificatesWatcher(options *CertWatcherOptions, pemFilePaths ...string) *Client

SetRootCertificatesWatcher method enables dynamic reloading of one or more root certificate files. It is designed for scenarios involving long-running Resty clients where certificates may be renewed.

client.SetRootCertificatesWatcher(
	&resty.CertWatcherOptions{
		PoolInterval: 24 * time.Hour,
	},
	"root-ca.pem",
)

func (*Client) SetSaveResponse ¶

func (c *Client) SetSaveResponse(save bool) *Client

SetSaveResponse method used to enable the save response option at the client level for all requests

client.SetSaveResponse(true)

Resty determines the save filename in the following order -

• Request.SetOutputFileName
• Content-Disposition header
• Request URL using path.Base
• Request URL hostname if path is empty or "/"

It can be overridden at request level, see Request.SetSaveResponse

func (*Client) SetScheme ¶

func (c *Client) SetScheme(scheme string) *Client

SetScheme method sets a custom scheme for the Resty client. It's a way to override the default.

client.SetScheme("http")

func (*Client) SetTLSClientConfig ¶

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

SetTLSClientConfig method sets TLSClientConfig for underlying client Transport.

Values supported by https://pkg.go.dev/crypto/tls#Config can be configured.

// Disable SSL cert verification for local development
client.SetTLSClientConfig(&tls.Config{
	InsecureSkipVerify: true
})

NOTE: This method overwrites existing http.Transport.TLSClientConfig

func (*Client) SetTimeout ¶

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

SetTimeout method is used to set a timeout for a request raised by the client.

client.SetTimeout(1 * time.Minute)

It can be overridden at the request level. See Request.SetTimeout

NOTE: Resty uses context.WithTimeout on the request, it does not use http.Client.Timeout

func (*Client) SetTrace ¶

func (c *Client) SetTrace(t bool) *Client

SetTrace method is used to turn on/off the trace capability in the Resty client Refer to Client.EnableTrace or Client.DisableTrace.

Also, see Request.SetTrace

func (*Client) SetTransport ¶

func (c *Client) SetTransport(transport http.RoundTripper) *Client

SetTransport method sets custom http.Transport or any http.RoundTripper compatible interface implementation in the Resty client.

transport := &http.Transport{
	// something like Proxying to httptest.Server, etc...
	Proxy: func(req *http.Request) (*url.URL, error) {
		return url.Parse(server.URL)
	},
}
client.SetTransport(transport)

NOTE:

• If transport is not the type of http.Transport, you may lose the ability to set a few Resty client settings. However, if you implement TLSClientConfiger interface, then TLS client config is possible to set.
• It overwrites the Resty client transport instance and its configurations.

func (*Client) SetUnescapeQueryParams ¶

func (c *Client) SetUnescapeQueryParams(unescape bool) *Client

SetUnescapeQueryParams method sets the choice of unescape query parameters for the request URL. To prevent broken URL, Resty replaces space (" ") with "+" in the query parameters.

See Request.SetUnescapeQueryParams

NOTE: Request failure is possible due to non-standard usage of Unescaped Query Parameters.

func (*Client) TLSClientConfig ¶

func (c *Client) TLSClientConfig() *tls.Config

TLSClientConfig method returns the tls.Config from underlying client transport otherwise returns nil

func (*Client) Timeout ¶

func (c *Client) Timeout() time.Duration

Timeout method returns the timeout duration value from the client

func (*Client) Transport ¶

func (c *Client) Transport() http.RoundTripper

Transport method returns underlying client transport referance as-is i.e., http.RoundTripper

func (*EventSource) AddEventListener ¶

func (es *EventSource) AddEventListener(eventName string, ef EventMessageFunc, result any) *EventSource

AddEventListener method registers a callback to consume a specific event type messages from the server. The second result argument is optional; it can be used to register the data type for JSON data.

es.AddEventListener(
	"friend_logged_in",
	func(e any) {
		e = e.(*Event)
		fmt.Println(e)
	},
	nil,
)

// Receiving JSON data from the server, you can set result type
// to do auto-unmarshal
es.AddEventListener(
	"friend_logged_in",
	func(e any) {
		e = e.(*UserLoggedIn)
		fmt.Println(e)
	},
	UserLoggedIn{},
)

func (*EventSource) AddHeader ¶

func (es *EventSource) AddHeader(header, value string) *EventSource

AddHeader method adds a header and its value to the EventSource instance. If the header key already exists, it appends. These headers will be sent in the request while establishing a connection to the event source

es.AddHeader("Authorization", "token here").
	AddHeader("X-Header", "value")

func (*EventSource) Close ¶

func (es *EventSource) Close()

Close method used to close SSE connection explicitly

func (*EventSource) Get ¶

func (es *EventSource) Get() error

Get method establishes the connection with the server.

es := NewEventSource().
	SetURL("https://sse.dev/test").
	OnMessage(
		func(e any) {
			e = e.(*Event)
			fmt.Println(e)
		},
		nil, // see method godoc
	)

err := es.Get()
fmt.Println(err)

func (*EventSource) OnError ¶

func (es *EventSource) OnError(ef EventErrorFunc) *EventSource

OnError registered callback gets triggered when the error occurred in the process

es.OnError(func(err error) {
	fmt.Println("Error occurred:", err)
})

func (*EventSource) OnMessage ¶

func (es *EventSource) OnMessage(ef EventMessageFunc, result any) *EventSource

OnMessage method registers a callback to emit every SSE event message from the server. The second result argument is optional; it can be used to register the data type for JSON data.

es.OnMessage(
	func(e any) {
		e = e.(*Event)
		fmt.Println("Event message", e)
	},
	nil,
)

// Receiving JSON data from the server, you can set result type
// to do auto-unmarshal
es.OnMessage(
	func(e any) {
		e = e.(*MyData)
		fmt.Println(e)
	},
	MyData{},
)

func (*EventSource) OnOpen ¶

func (es *EventSource) OnOpen(ef EventOpenFunc) *EventSource

OnOpen registered callback gets triggered when the connection is established with the server

es.OnOpen(func(url string) {
	fmt.Println("I'm connected:", url)
})

func (*EventSource) SetBody ¶

func (es *EventSource) SetBody(body io.Reader) *EventSource

SetBody method sets body value to the EventSource instance

Example: es.SetBody(bytes.NewReader([]byte(`{"test":"put_data"}`)))

func (*EventSource) SetHeader ¶

func (es *EventSource) SetHeader(header, value string) *EventSource

SetHeader method sets a header and its value to the EventSource instance. It overwrites the header value if the key already exists. These headers will be sent in the request while establishing a connection to the event source

es.SetHeader("Authorization", "token here").
	SetHeader("X-Header", "value")

func (*EventSource) SetLogger ¶

func (es *EventSource) SetLogger(l Logger) *EventSource

SetLogger method sets given writer for logging

Compliant to interface resty.Logger

func (*EventSource) SetMaxBufSize ¶

func (es *EventSource) SetMaxBufSize(bufSize int) *EventSource

SetMaxBufSize method sets the given buffer size into the SSE client

Default is 32kb

es.SetMaxBufSize(64 * 1024) // 64kb

func (*EventSource) SetMethod ¶

func (es *EventSource) SetMethod(method string) *EventSource

SetMethod method sets a EventSource connection HTTP method in the instance

es.SetMethod("POST"), or es.SetMethod(resty.MethodPost)

func (*EventSource) SetRetryCount ¶

func (es *EventSource) SetRetryCount(count int) *EventSource

SetRetryCount method enables retry attempts on the SSE client while establishing connection with the server

first attempt + retry count = total attempts

Default is 3

es.SetRetryCount(10)

func (*EventSource) SetRetryMaxWaitTime ¶

func (es *EventSource) SetRetryMaxWaitTime(maxWaitTime time.Duration) *EventSource

SetRetryMaxWaitTime method sets the max wait time for sleep before retrying the request

Default is 2 seconds.

NOTE: The server-sent retry value takes precedence if present.

es.SetRetryMaxWaitTime(3 * time.Second)

func (*EventSource) SetRetryWaitTime ¶

func (es *EventSource) SetRetryWaitTime(waitTime time.Duration) *EventSource

SetRetryWaitTime method sets the default wait time for sleep before retrying the request

Default is 100 milliseconds.

NOTE: The server-sent retry value takes precedence if present.

es.SetRetryWaitTime(1 * time.Second)

func (*EventSource) SetURL ¶

func (es *EventSource) SetURL(url string) *EventSource

SetURL method sets a EventSource connection URL in the instance

es.SetURL("https://sse.dev/test")

func (*MultipartField) Clone ¶

func (mf *MultipartField) Clone() *MultipartField

Clone method returns the deep copy of m except io.Reader.

func (MultipartFieldProgress) String ¶

func (mfp MultipartFieldProgress) String() string

String method creates the string representation of MultipartFieldProgress

func (RedirectPolicyFunc) Apply ¶

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

Apply calls f(req, via).

func (*Request) AddRetryConditions ¶

func (r *Request) AddRetryConditions(conditions ...RetryConditionFunc) *Request

AddRetryConditions method adds one or more retry condition functions into the request. These retry conditions are executed to determine if the request can be retried. The request will retry if any functions return `true`, otherwise return `false`.

NOTE:

• The default retry conditions are applied first.
• The client-level retry conditions are applied to all requests.
• The request-level retry conditions are executed first before the client-level retry conditions. See Request.SetRetryConditions

func (*Request) AddRetryHooks ¶

func (r *Request) AddRetryHooks(hooks ...RetryHookFunc) *Request

AddRetryHooks method adds one or more side-effecting retry hooks in the request.

NOTE:

• All the retry hooks are executed on each request retry.
• The request-level retry hooks are executed first before the client-level hooks.

func (*Request) Clone ¶

func (r *Request) Clone(ctx context.Context) *Request

Clone returns a deep copy of r with its context changed to ctx. It does clone appropriate fields, reset, and reinitialize, so Request can be used again.

The body is not copied, but it's a reference to the original body.

req := client.R().
	SetBody("body").
	SetHeader("header", "value")
clonedRequest := req.Clone(context.Background())

func (*Request) Context ¶

func (r *Request) Context() context.Context

Context method returns the request's context.Context. To change the context, use Request.Clone or Request.WithContext.

The returned context is always non-nil; it defaults to the background context.

func (*Request) CurlCmd ¶

func (r *Request) CurlCmd() string

CurlCmd method generates the curl command for the request.

func (*Request) Delete ¶

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

Delete method does DELETE HTTP request. It's defined in section 9.3.5 of RFC 9110.

func (*Request) DisableDebug ¶

func (r *Request) DisableDebug() *Request

DisableDebug method is a helper method for Request.SetDebug

func (*Request) DisableGenerateCurlCmd ¶

func (r *Request) DisableGenerateCurlCmd() *Request

DisableGenerateCurlCmd method disables the option set by Request.EnableGenerateCurlCmd or Request.SetGenerateCurlCmd.

It overrides the options set in the Client.

func (*Request) DisableRetryDefaultConditions ¶

func (r *Request) DisableRetryDefaultConditions() *Request

DisableRetryDefaultConditions method disables the Resty's default retry conditions on request level

func (*Request) DisableTrace ¶

func (r *Request) DisableTrace() *Request

DisableTrace method disables the request trace for the current request

func (*Request) EnableDebug ¶

func (r *Request) EnableDebug() *Request

EnableDebug method is a helper method for Request.SetDebug

func (*Request) EnableGenerateCurlCmd ¶

func (r *Request) EnableGenerateCurlCmd() *Request

EnableGenerateCurlCmd method enables the generation of curl commands for the current request.

By default, Resty does not log the curl command in the debug log since it has the potential to leak sensitive data unless explicitly enabled via Request.SetDebugLogCurlCmd or Client.SetDebugLogCurlCmd.

It overrides the options set in the Client.

NOTE: Use with care.

• Potential to leak sensitive data from Request and Response in the debug log when the debug log option is enabled.
• Additional memory usage since the request body was reread.
• curl body is not generated for io.Reader and multipart request flow.

func (*Request) EnableRetryDefaultConditions ¶

func (r *Request) EnableRetryDefaultConditions() *Request

EnableRetryDefaultConditions method enables the Resty's default retry conditions on request level

func (*Request) EnableTrace ¶

func (r *Request) EnableTrace() *Request

EnableTrace method enables trace for the current request using httptrace.ClientTrace and provides insights.

client := resty.New()

resp, err := client.R().EnableTrace().Get("https://httpbin.org/get")
fmt.Println("Error:", err)
fmt.Println("Trace Info:", resp.Request.TraceInfo())

See Client.EnableTrace, Client.SetTrace are also available to get trace info for all requests.

func (*Request) Execute ¶

func (r *Request) Execute(method, url string) (res *Response, err error)

Execute method performs the HTTP request with the given HTTP method and URL for current Request.

resp, err := client.R().Execute(resty.MethodGet, "http://httpbin.org/get")

func (*Request) Funcs ¶

func (r *Request) Funcs(funcs ...RequestFunc) *Request

Funcs method gets executed on request composition that passes the current request instance to provided RequestFunc, which could be used to apply common/reusable logic to the given request instance.

func addRequestContentType(r *Request) *Request {
	return r.SetHeader("Content-Type", "application/json").
		SetHeader("Accept", "application/json")
}

func addRequestQueryParams(page, size int) func(r *Request) *Request {
	return func(r *Request) *Request {
		return r.SetQueryParam("page", strconv.Itoa(page)).
			SetQueryParam("size", strconv.Itoa(size)).
			SetQueryParam("request_no", strconv.Itoa(int(time.Now().Unix())))
	}
}

client.R().
	Funcs(addRequestContentType, addRequestQueryParams(1, 100)).
	Get("https://localhost:8080/foobar")

func (*Request) Get ¶

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

Get method does GET HTTP request. It's defined in section 9.3.1 of RFC 9110.

func (*Request) Head ¶

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

Head method does HEAD HTTP request. It's defined in section 9.3.2 of RFC 9110.

func (*Request) Options ¶

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

Options method does OPTIONS HTTP request. It's defined in section 9.3.7 of RFC 9110.

func (*Request) Patch ¶

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

Patch method does PATCH HTTP request. It's defined in section 2 of RFC 5789.

func (*Request) Post ¶

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

Post method does POST HTTP request. It's defined in section 9.3.3 of RFC 9110.

func (*Request) Put ¶

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

Put method does PUT HTTP request. It's defined in section 9.3.4 of RFC 9110.

func (*Request) Send ¶

func (r *Request) Send() (*Response, error)

Send method performs the HTTP request using the method and URL already defined for current Request.

res, err := client.R().
	SetMethod(resty.MethodGet).
	SetURL("http://httpbin.org/get").
	Send()

func (*Request) SetAllowMethodDeletePayload ¶

func (r *Request) SetAllowMethodDeletePayload(allow bool) *Request

SetAllowMethodDeletePayload method allows the DELETE method with payload on the request level. By default, Resty does not allow.

client.R().SetAllowMethodDeletePayload(true)

More info, refer to GH#881

It overrides the option set by the Client.SetAllowMethodDeletePayload

func (*Request) SetAllowMethodGetPayload ¶

func (r *Request) SetAllowMethodGetPayload(allow bool) *Request

SetAllowMethodGetPayload method allows the GET method with payload on the request level. By default, Resty does not allow.

client.R().SetAllowMethodGetPayload(true)

It overrides the option set by the Client.SetAllowMethodGetPayload

func (*Request) SetAllowNonIdempotentRetry ¶

func (r *Request) SetAllowNonIdempotentRetry(b bool) *Request

SetAllowNonIdempotentRetry method is used to enable/disable non-idempotent HTTP methods retry. By default, Resty only allows idempotent HTTP methods, see RFC 9110 Section 9.2.2, RFC 9110 Section 18.2

It overrides value set at the client instance level, see Client.SetAllowNonIdempotentRetry

func (*Request) SetAuthScheme ¶

func (r *Request) SetAuthScheme(scheme string) *Request

SetAuthScheme method sets the auth token scheme type in the HTTP request.

Example Header value structure:

Authorization: <auth-scheme-value-set-here> <auth-token-value>

For Example: To set the scheme to use OAuth

client.R().SetAuthScheme("OAuth")

// The outcome will be -
Authorization: OAuth <auth-token-value>

Information about Auth schemes can be found in RFC 7235, IANA HTTP Auth schemes

It overrides the `Authorization` scheme set by method Client.SetAuthScheme.

func (*Request) SetAuthToken ¶

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

SetAuthToken method sets the auth token header(Default Scheme: Bearer) in the current HTTP request. Header example:

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

For Example: To set auth token BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F

client.R().SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F")

It overrides the Auth token set by method Client.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 Example:

Authorization: Basic <base64-encoded-value>

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

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

It overrides the credentials set by method Client.SetBasicAuth.

func (*Request) SetBody ¶

func (r *Request) SetBody(body any) *Request

SetBody method sets the request body for the request. It supports various practical needs as easy. It's quite handy and powerful. Supported request body data types are `string`, `[]byte`, `struct`, `map`, `slice` and io.Reader.

Body value can be pointer or non-pointer. Automatic marshalling for JSON and XML content type, if it is `struct`, `map`, or `slice`.

NOTE: io.Reader is processed in bufferless mode while sending a request.

For Example:

`struct` gets marshaled based on the request header `Content-Type`.

client.R().
	SetBody(User{
		Username: "[email protected]",
		Password: "welcome2resty",
	})

'map` gets marshaled based on the request header `Content-Type`.

client.R().
	SetBody(map[string]any{
		"username": "[email protected]",
		"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.

client.R().
	SetBody(`{
		"username": "[email protected]",
		"password": "admin"
	}`)

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

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

and so on.

func (*Request) SetCloseConnection ¶

func (r *Request) SetCloseConnection(close bool) *Request

SetCloseConnection method sets variable `Close` in HTTP request struct with the given value. More info: https://golang.org/src/net/http/request.go

It overrides the value set at the client instance level, see Client.SetCloseConnection

func (*Request) SetContentLength ¶

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

SetContentLength method sets the current request's HTTP header `Content-Length` value. By default, Resty won't set `Content-Length`.

See Client.SetContentLength

client.R().SetContentLength(true)

It overrides the value set at the client instance level.

func (*Request) SetContentType ¶

func (r *Request) SetContentType(ct string) *Request

SetContentType method is a convenient way to set the header Content-Type in the request

client.R().SetContentType("application/json")

func (*Request) SetContext ¶

func (r *Request) SetContext(ctx context.Context) *Request

SetContext method sets the context.Context for current Request. It overwrites the current context in the Request instance; it does not affect the Request.RawRequest that was already created.

If you want this method to take effect, use this method before invoking Request.Send or Request.HTTPVerb methods.

See Request.WithContext, Request.Clone

func (*Request) SetCookie ¶

func (r *Request) SetCookie(hc *http.Cookie) *Request

SetCookie method appends a single cookie in the current request instance.

client.R().SetCookie(&http.Cookie{
			Name:"go-resty",
			Value:"This is cookie value",
		})

NOTE: Method appends the Cookie value into existing Cookie even if its already existing.

func (*Request) SetCookies ¶

func (r *Request) SetCookies(rs []*http.Cookie) *Request

SetCookies method sets an array of cookies in the current request instance.

cookies := []*http.Cookie{
	&http.Cookie{
		Name:"go-resty-1",
		Value:"This is cookie 1 value",
	},
	&http.Cookie{
		Name:"go-resty-2",
		Value:"This is cookie 2 value",
	},
}

// Setting a cookies into resty's current request
client.R().SetCookies(cookies)

NOTE: Method appends the Cookie value into existing Cookie even if its already existing.

func (*Request) SetDebug ¶

func (r *Request) SetDebug(d bool) *Request

SetDebug method enables the debug mode on the current request. It logs the details current request and response.

client.R().SetDebug(true)
// OR
client.R().EnableDebug()

Also, it can be enabled at the request level for a particular request; see Request.SetDebug.

• For Request, it logs information such as HTTP verb, Relative URL path, Host, Headers, and Body if it has one.
• For Response, it logs information such as Status, Response Time, Headers, and Body if it has one.

func (*Request) SetDebugLogCurlCmd ¶

func (r *Request) SetDebugLogCurlCmd(b bool) *Request

SetDebugLogCurlCmd method enables the curl command to be logged in the debug log for the current request.

It can be overridden at the request level; see Client.SetDebugLogCurlCmd

func (*Request) SetDoNotParseResponse ¶

func (r *Request) SetDoNotParseResponse(notParse bool) *Request

SetDoNotParseResponse method instructs Resty not to parse the response body automatically.

Resty exposes the raw response body as io.ReadCloser. If you use it, do not forget to close the body, otherwise, you might get into connection leaks, and connection reuse may not happen.

NOTE: The default Response middlewares are not executed when using this option. User takes over the control of handling response body from Resty.

func (*Request) SetError ¶

func (r *Request) SetError(err any) *Request

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

NOTE: Request.SetError input can be a pointer or non-pointer.

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

Accessing an error value from response instance.

response.Error().(*AuthError)

If this request Error object is nil, Resty will use the client-level error object Type if it is set.

func (*Request) SetExpectResponseContentType ¶

func (r *Request) SetExpectResponseContentType(contentType string) *Request

SetExpectResponseContentType method allows to provide fallback `Content-Type` for automatic unmarshalling when the `Content-Type` response header is unavailable.

func (*Request) SetFile ¶

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

SetFile method sets a single file field name and its path for multipart upload.

Resty provides an optional multipart live upload progress callback; see method Request.SetMultipartFields

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

func (*Request) SetFileReader ¶

func (r *Request) SetFileReader(fieldName, fileName string, reader io.Reader) *Request

SetFileReader method is to set a file using io.Reader for multipart upload.

Resty provides an optional multipart live upload progress callback; see method Request.SetMultipartFields

client.R().
	SetFileReader("profile_img", "my-profile-img.png", bytes.NewReader(profileImgBytes)).
	SetFileReader("notes", "user-notes.txt", bytes.NewReader(notesBytes))

func (*Request) SetFiles ¶

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

SetFiles method sets multiple file field names and their paths for multipart uploads.

Resty provides an optional multipart live upload progress callback; see method Request.SetMultipartFields

client.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) SetForceResponseContentType ¶

func (r *Request) SetForceResponseContentType(contentType string) *Request

SetForceResponseContentType method provides a strong sense of response `Content-Type` for automatic unmarshalling. Resty gives this a higher priority than the `Content-Type` response header.

This means that if both Request.SetForceResponseContentType is set and the response `Content-Type` is available, `SetForceResponseContentType` value will win.

func (*Request) SetFormData ¶

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

SetFormData method sets form parameters and their values in the current request. The request content type would be set as `application/x-www-form-urlencoded`.

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

It overrides the form data value set at the client instance level.

See Request.SetFormDataFromValues for the same field name with multiple values.

func (*Request) SetFormDataFromValues ¶

func (r *Request) SetFormDataFromValues(data url.Values) *Request

SetFormDataFromValues method appends multiple form parameters with multi-value (url.Values) at one go in the current request.

client.R().
	SetFormDataFromValues(url.Values{
		"search_criteria": []string{"book", "glass", "pencil"},
	})

It overrides the form data value set at the client instance level.

func (*Request) SetGenerateCurlCmd ¶

func (r *Request) SetGenerateCurlCmd(b bool) *Request

SetGenerateCurlCmd method is used to turn on/off the generate curl command for the current request.

By default, Resty does not log the curl command in the debug log since it has the potential to leak sensitive data unless explicitly enabled via Request.SetDebugLogCurlCmd or Client.SetDebugLogCurlCmd.

It overrides the options set by the Client.SetGenerateCurlCmd

NOTE: Use with care.

• Potential to leak sensitive data from Request and Response in the debug log when the debug log option is enabled.
• Additional memory usage since the request body was reread.
• curl body is not generated for io.Reader and multipart request flow.

func (*Request) SetHeader ¶

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

SetHeader method sets a single header field and its value in the current request.

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

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

It overrides the header value set at the client instance level.

func (*Request) SetHeaderAuthorizationKey ¶

func (r *Request) SetHeaderAuthorizationKey(k string) *Request

SetHeaderAuthorizationKey method sets the given HTTP header name for Authorization in the request.

It overrides the `Authorization` header name set by method Client.SetHeaderAuthorizationKey.

client.R().SetHeaderAuthorizationKey("X-Custom-Authorization")

func (*Request) SetHeaderMultiValues ¶

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

SetHeaderMultiValues sets multiple header fields and their values as a list of strings in the current request.

For Example: To set `Accept` as `text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8`

client.R().
	SetHeaderMultiValues(map[string][]string{
		"Accept": []string{"text/html", "application/xhtml+xml", "application/xml;q=0.9", "image/webp", "*/*;q=0.8"},
	})

It overrides the header value set at the client instance level.

func (*Request) SetHeaderVerbatim ¶

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

SetHeaderVerbatim method is used to set the HTTP header key and value verbatim in the current request. It is typically helpful for legacy applications or servers that require HTTP headers in a certain way

For Example: To set header key as `all_lowercase`, `UPPERCASE`, and `x-cloud-trace-id`

client.R().
	SetHeaderVerbatim("all_lowercase", "available").
	SetHeaderVerbatim("UPPERCASE", "available").
	SetHeaderVerbatim("x-cloud-trace-id", "798e94019e5fc4d57fbb8901eb4c6cae")

It overrides the header value set at the client instance level.

func (*Request) SetHeaders ¶

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

SetHeaders method sets multiple header fields and their values at one go in the current request.

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

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

It overrides the header value set at the client instance level.

func (*Request) SetJSONEscapeHTML ¶

func (r *Request) SetJSONEscapeHTML(b bool) *Request

SetJSONEscapeHTML method enables or disables the HTML escape on JSON marshal. By default, escape HTML is `true`.

NOTE: This option only applies to the standard JSON Marshaller used by Resty.

It overrides the value set at the client instance level, see Client.SetJSONEscapeHTML

func (*Request) SetLogger ¶

func (r *Request) SetLogger(l Logger) *Request

SetLogger method sets given writer for logging Resty request and response details. By default, requests and responses inherit their logger from the client.

Compliant to interface resty.Logger.

It overrides the logger value set at the client instance level.

func (*Request) SetMethod ¶

func (r *Request) SetMethod(m string) *Request

SetMethod method used to set the HTTP verb for the request

func (*Request) SetMultipartBoundary ¶

func (r *Request) SetMultipartBoundary(boundary string) *Request

SetMultipartBoundary method sets the custom multipart boundary for the multipart request. Typically, the `mime/multipart` package generates a random multipart boundary if not provided.

func (*Request) SetMultipartField ¶

func (r *Request) SetMultipartField(fieldName, fileName, contentType string, reader io.Reader) *Request

SetMultipartField method sets custom data with Content-Type using io.Reader for multipart upload.

Resty provides an optional multipart live upload progress callback; see method Request.SetMultipartFields

func (*Request) SetMultipartFields ¶

func (r *Request) SetMultipartFields(fields ...*MultipartField) *Request

SetMultipartFields method sets multiple data fields using io.Reader for multipart upload.

Resty provides an optional multipart live upload progress count in bytes; see MultipartField.ProgressCallback and MultipartFieldProgress

For Example:

client.R().SetMultipartFields(
	&resty.MultipartField{
		Name:        "uploadManifest1",
		FileName:    "upload-file-1.json",
		ContentType: "application/json",
		Reader:      strings.NewReader(`{"input": {"name": "Uploaded document 1", "_filename" : ["file1.txt"]}}`),
	},
	&resty.MultipartField{
		Name:        "uploadManifest2",
		FileName:    "upload-file-2.json",
		ContentType: "application/json",
		FilePath:    "/path/to/upload-file-2.json",
	},
	&resty.MultipartField{
		Name:             "image-file1",
		FileName:         "image-file1.png",
		ContentType:      "image/png",
		Reader:           bytes.NewReader(fileBytes),
		ProgressCallback: func(mp MultipartFieldProgress) {
			// use the progress details
		},
	},
	&resty.MultipartField{
		Name:             "image-file2",
		FileName:         "image-file2.png",
		ContentType:      "image/png",
		Reader:           imageFile2, // instance of *os.File
		ProgressCallback: func(mp MultipartFieldProgress) {
			// use the progress details
		},
	})

If you have a `slice` of fields already, then call-

client.R().SetMultipartFields(fields...)

func (*Request) SetMultipartFormData ¶

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

SetMultipartFormData method allows simple form data to be attached to the request as `multipart:form-data`

func (*Request) SetMultipartOrderedFormData ¶

func (r *Request) SetMultipartOrderedFormData(name string, values []string) *Request

SetMultipartOrderedFormData method allows add ordered form data to be attached to the request as `multipart:form-data`

func (*Request) SetOutputFileName ¶

func (r *Request) SetOutputFileName(file string) *Request

SetOutputFileName method sets the output file for the current HTTP request. The current HTTP response will be saved in the given file. It is similar to the `curl -o` flag.

Absolute path or relative path can be used.

If it is a relative path, then the output file goes under the output directory, as mentioned in the Client.SetOutputDirectory.

client.R().
	SetOutputFileName("/Users/jeeva/Downloads/ReplyWithHeader-v5.1-beta.zip").
	Get("http://bit.ly/1LouEKr")

NOTE: In this scenario

• [Response.BodyBytes] might be nil.
• Response.Body might have been already read.

func (*Request) SetPathParam ¶

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

SetPathParam method sets a single URL path key-value pair in the Resty current request instance.

client.R().SetPathParam("userId", "[email protected]")

Result:
   URL - /v1/users/{userId}/details
   Composed URL - /v1/users/[email protected]/details

client.R().SetPathParam("path", "groups/developers")

Result:
   URL - /v1/users/{path}/details
   Composed URL - /v1/users/groups%2Fdevelopers/details

It replaces the value of the key while composing the request URL. The values will be escaped using function url.PathEscape.

It overrides the path parameter set at the client instance level.

func (*Request) SetPathParams ¶

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

SetPathParams method sets multiple URL path key-value pairs at one go in the Resty current request instance.

client.R().SetPathParams(map[string]string{
	"userId":       "[email protected]",
	"subAccountId": "100002",
	"path":         "groups/developers",
})

Result:
   URL - /v1/users/{userId}/{subAccountId}/{path}/details
   Composed URL - /v1/users/[email protected]/100002/groups%2Fdevelopers/details

It replaces the value of the key while composing the request URL. The values will be escaped using function url.PathEscape.

It overrides the path parameter set at the client instance level.

func (*Request) SetQueryParam ¶

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

SetQueryParam method sets a single parameter and its value in the current request. It will be formed as a query string for the request.

For Example: `search=kitchen%20papers&size=large` in the URL after the `?` mark.

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

It overrides the query parameter value set at the client instance level.

func (*Request) SetQueryParams ¶

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

SetQueryParams method sets multiple parameters and their values at one go in the current request. It will be formed as a query string for the request.

For Example: `search=kitchen%20papers&size=large` in the URL after the `?` mark.

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

It overrides the query parameter value set at the client instance level.

func (*Request) SetQueryParamsFromValues ¶

func (r *Request) SetQueryParamsFromValues(params url.Values) *Request

SetQueryParamsFromValues method appends multiple parameters with multi-value (url.Values) at one go in the current request. It will be formed as query string for the request.

For Example: `status=pending&status=approved&status=open` in the URL after the `?` mark.

client.R().
	SetQueryParamsFromValues(url.Values{
		"status": []string{"pending", "approved", "open"},
	})

It overrides the query parameter value set at the client instance level.

func (*Request) SetQueryString ¶

func (r *Request) SetQueryString(query string) *Request

SetQueryString method provides the ability to use string as an input to set URL query string for the request.

client.R().
	SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more")

It overrides the query parameter value set at the client instance level.

func (*Request) SetRawPathParam ¶

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

SetRawPathParam method sets a single URL path key-value pair in the Resty current request instance without path escape.

client.R().SetRawPathParam("userId", "[email protected]")

Result:
   URL - /v1/users/{userId}/details
   Composed URL - /v1/users/[email protected]/details

client.R().SetRawPathParam("path", "groups/developers")

Result:
   URL - /v1/users/{path}/details
   Composed URL - /v1/users/groups/developers/details

It replaces the value of the key while composing the request URL. The value will be used as-is, no path escape applied.

It overrides the raw path parameter set at the client instance level.

func (*Request) SetRawPathParams ¶

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

SetRawPathParams method sets multiple URL path key-value pairs at one go in the Resty current request instance without path escape.

client.R().SetPathParams(map[string]string{
	"userId": "[email protected]",
	"subAccountId": "100002",
	"path":         "groups/developers",
})

Result:
   URL - /v1/users/{userId}/{subAccountId}/{path}/details
   Composed URL - /v1/users/[email protected]/100002/groups/developers/details

It replaces the value of the key while composing the request URL. The value will be used as-is, no path escape applied.

It overrides the raw path parameter set at the client instance level.

func (*Request) SetResponseBodyLimit ¶

func (r *Request) SetResponseBodyLimit(v int64) *Request

SetResponseBodyLimit method sets a maximum body size limit in bytes on response, avoid reading too much data to memory.

Client will return resty.ErrResponseBodyTooLarge if the body size of the body in the uncompressed response is larger than the limit. Body size limit will not be enforced in the following cases:

• ResponseBodyLimit <= 0, which is the default behavior.
• Request.SetOutputFileName is called to save response data to the file.
• "DoNotParseResponse" is set for client or request.

It overrides the value set at the client instance level, see Client.SetResponseBodyLimit

func (*Request) SetResponseBodyUnlimitedReads ¶

func (r *Request) SetResponseBodyUnlimitedReads(b bool) *Request

SetResponseBodyUnlimitedReads method is to turn on/off the response body in memory that provides an ability to do unlimited reads.

It overrides the value set at the client level; see Client.SetResponseBodyUnlimitedReads

Unlimited reads are possible in a few scenarios, even without enabling it.

• When debug mode is enabled

NOTE: Use with care

• Turning on this feature keeps the response body in memory, which might cause additional memory usage.

func (*Request) SetResult ¶

func (r *Request) SetResult(v any) *Request

SetResult method is to register the response `Result` object for automatic unmarshalling of the HTTP response if the response status code is between 200 and 299, and the content type is JSON or XML.

Note: Request.SetResult input can be a pointer or non-pointer.

The pointer with handle

authToken := &AuthToken{}
client.R().SetResult(authToken)

// Can be accessed via -
fmt.Println(authToken) OR fmt.Println(response.Result().(*AuthToken))

OR -

The pointer without handle or non-pointer

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

// Can be accessed via -
fmt.Println(response.Result().(*AuthToken))

func (*Request) SetRetryConditions ¶

func (r *Request) SetRetryConditions(conditions ...RetryConditionFunc) *Request

SetRetryConditions method overwrites the retry conditions in the request. These retry conditions are executed to determine if the request can be retried. The request will retry if any function returns `true`, otherwise return `false`.

func (*Request) SetRetryCount ¶

func (r *Request) SetRetryCount(count int) *Request

SetRetryCount method enables retry on Resty client and allows you to set no. of retry count.

first attempt + retry count = total attempts

See Request.SetRetryStrategy

NOTE:

• By default, Resty only does retry on idempotent HTTP verb, RFC 9110 Section 9.2.2, RFC 9110 Section 18.2

func (*Request) SetRetryDefaultConditions ¶

func (r *Request) SetRetryDefaultConditions(b bool) *Request

SetRetryDefaultConditions method is used to enable/disable the Resty's default retry conditions on request level

It overrides value set at the client instance level, see Client.SetRetryDefaultConditions

func (*Request) SetRetryHooks ¶

func (r *Request) SetRetryHooks(hooks ...RetryHookFunc) *Request

SetRetryHooks method overwrites side-effecting retry hooks in the request.

NOTE:

• All the retry hooks are executed on each request retry.

func (*Request) SetRetryMaxWaitTime ¶

func (r *Request) SetRetryMaxWaitTime(maxWaitTime time.Duration) *Request

SetRetryMaxWaitTime method sets the max wait time for sleep before retrying

Default is 2 seconds.

func (*Request) SetRetryStrategy ¶

func (r *Request) SetRetryStrategy(rs RetryStrategyFunc) *Request

SetRetryStrategy method used to set the custom Retry strategy on request, it is used to get wait time before each retry. It overrides the retry strategy set at the client instance level, see Client.SetRetryStrategy

Default (nil) implies capped exponential backoff with a jitter strategy

func (*Request) SetRetryWaitTime ¶

func (r *Request) SetRetryWaitTime(waitTime time.Duration) *Request

SetRetryWaitTime method sets the default wait time for sleep before retrying

Default is 100 milliseconds.

func (*Request) SetSaveResponse ¶

func (r *Request) SetSaveResponse(save bool) *Request

SetSaveResponse method used to enable the save response option for the current requests

client.R().SetSaveResponse(true)

Resty determines the save filename in the following order -

• Request.SetOutputFileName
• Content-Disposition header
• Request URL using path.Base
• Request URL hostname if path is empty or "/"

It overrides the value set at the client instance level, see Client.SetSaveResponse

func (*Request) SetTimeout ¶

func (r *Request) SetTimeout(timeout time.Duration) *Request

SetTimeout method is used to set a timeout for the current request

client.R().SetTimeout(1 * time.Minute)

It overrides the timeout set at the client instance level, See Client.SetTimeout

NOTE: Resty uses context.WithTimeout on the request, it does not use http.Client.Timeout

func (*Request) SetTrace ¶

func (r *Request) SetTrace(t bool) *Request

SetTrace method is used to turn on/off the trace capability at the request level

See Request.EnableTrace or Client.SetTrace

func (*Request) SetURL ¶

func (r *Request) SetURL(url string) *Request

SetURL method used to set the request URL for the request

func (*Request) SetUnescapeQueryParams ¶

func (r *Request) SetUnescapeQueryParams(unescape bool) *Request

SetUnescapeQueryParams method sets the choice of unescape query parameters for the request URL. To prevent broken URL, Resty replaces space (" ") with "+" in the query parameters.

This method overrides the value set by Client.SetUnescapeQueryParams

NOTE: Request failure is possible due to non-standard usage of Unescaped Query Parameters.

func (*Request) Trace ¶

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

Trace method does TRACE HTTP request. It's defined in section 9.3.8 of RFC 9110.

func (*Request) TraceInfo ¶

func (r *Request) TraceInfo() TraceInfo

TraceInfo method returns the trace info for the request. If either the Client.EnableTrace or Request.EnableTrace function has not been called before the request is made, an empty resty.TraceInfo object is returned.

func (*Request) WithContext ¶

func (r *Request) WithContext(ctx context.Context) *Request

WithContext method returns a shallow copy of r with its context changed to ctx. The provided ctx must be non-nil. It does not affect the Request.RawRequest that was already created.

If you want this method to take effect, use this method before invoking Request.Send or Request.HTTPVerb methods.

See Request.SetContext, Request.Clone

func (*Response) Bytes ¶

func (r *Response) Bytes() []byte

Bytes method returns the body of the HTTP response as a byte slice. It returns an empty byte slice if it is nil or the body is zero length.

NOTE:

• Returns an empty byte slice on auto-unmarshal scenarios, unless Client.SetResponseBodyUnlimitedReads or Request.SetResponseBodyUnlimitedReads set.
• Returns an empty byte slice when Client.SetDoNotParseResponse or Request.SetDoNotParseResponse set.

func (*Response) Cookies ¶

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

Cookies method to returns all the response cookies

func (*Response) Duration ¶

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

Duration method returns the duration of HTTP response time from the request we sent and received a request.

See Response.ReceivedAt to know when the client received a response and see `Response.Request.Time` to know when the client sent a request.

func (*Response) Error ¶

func (r *Response) Error() any

Error method returns the error object if it has one

See Request.SetError, Client.SetError

func (*Response) Header ¶

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

Header method returns the response headers

func (*Response) IsError ¶

func (r *Response) IsError() bool

IsError method returns true if HTTP status `code >= 400` otherwise false.

func (*Response) IsSuccess ¶

func (r *Response) IsSuccess() bool

IsSuccess method returns true if HTTP status `code >= 200 and <= 299` otherwise false.

func (*Response) Proto ¶

func (r *Response) Proto() string

Proto method returns the HTTP response protocol used for the request.

func (*Response) ReceivedAt ¶

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

ReceivedAt method returns the time we received a response from the server for the request.

func (*Response) RedirectHistory ¶

func (r *Response) RedirectHistory() []*RedirectInfo

RedirectHistory method returns a redirect history slice with the URL and status code

func (*Response) Result ¶

func (r *Response) Result() any

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

See Request.SetResult

func (*Response) Size ¶

func (r *Response) Size() int64

Size method returns the HTTP response size in bytes. Yeah, you can rely on HTTP `Content-Length` header, however it won't be available for chucked transfer/compressed response. Since Resty captures response size details when processing the response body when possible. So that users get the actual size of response bytes.

func (*Response) Status ¶

func (r *Response) Status() string

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

Example: 200 OK

func (*Response) StatusCode ¶

func (r *Response) StatusCode() int

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

Example: 200

func (*Response) String ¶

func (r *Response) String() string

String method returns the body of the HTTP response as a `string`. It returns an empty string if it is nil or the body is zero length.

NOTE:

• Returns an empty string on auto-unmarshal scenarios, unless Client.SetResponseBodyUnlimitedReads or Request.SetResponseBodyUnlimitedReads set.
• Returns an empty string when Client.SetDoNotParseResponse or Request.SetDoNotParseResponse set.

func (*ResponseError) Error ¶

func (e *ResponseError) Error() string

func (*ResponseError) Unwrap ¶

func (e *ResponseError) Unwrap() error

func (*RoundRobin) Close ¶

func (rr *RoundRobin) Close() error

Close method does nothing in Round-Robin(RR) request load balancer

func (*RoundRobin) Feedback ¶

func (rr *RoundRobin) Feedback(_ *RequestFeedback)

Feedback method does nothing in Round-Robin(RR) request load balancer

func (*RoundRobin) Next ¶

func (rr *RoundRobin) Next() (string, error)

Next method returns the next Base URL based on the Round-Robin(RR) algorithm

func (*RoundRobin) Refresh ¶

func (rr *RoundRobin) Refresh(baseURLs ...string) error

Refresh method reset the existing Base URLs with the given Base URLs slice to refresh it

func (*SRVWeightedRoundRobin) Close ¶

func (swrr *SRVWeightedRoundRobin) Close() error

Close method does the cleanup by stopping the time.Ticker SRV Base URL based on Weighted Round-Robin(WRR) request load balancer

func (*SRVWeightedRoundRobin) Feedback ¶

func (swrr *SRVWeightedRoundRobin) Feedback(f *RequestFeedback)

Feedback method does nothing in SRV Base URL based on Weighted Round-Robin(WRR) request load balancer

func (*SRVWeightedRoundRobin) Next ¶

func (swrr *SRVWeightedRoundRobin) Next() (string, error)

Next method returns the next SRV Base URL based on Weighted Round-Robin(RR)

func (*SRVWeightedRoundRobin) Refresh ¶

func (swrr *SRVWeightedRoundRobin) Refresh() error

Refresh method reset the values based net.LookupSRV values to refresh it

func (*SRVWeightedRoundRobin) SetOnStateChange ¶

func (swrr *SRVWeightedRoundRobin) SetOnStateChange(fn HostStateChangeFunc)

SetOnStateChange method used to set a callback for the host transition state

func (*SRVWeightedRoundRobin) SetRecoveryDuration ¶

func (swrr *SRVWeightedRoundRobin) SetRecoveryDuration(d time.Duration)

SetRecoveryDuration method is used to change the existing recovery duration for the host

func (*SRVWeightedRoundRobin) SetRefreshDuration ¶

func (swrr *SRVWeightedRoundRobin) SetRefreshDuration(d time.Duration)

SetRefreshDuration method assists in changing the default (180 seconds) refresh duration

func (TraceInfo) Clone ¶

func (ti TraceInfo) Clone() *TraceInfo

Clone method returns the clone copy of TraceInfo

func (TraceInfo) JSON ¶

func (ti TraceInfo) JSON() string

JSON method returns the JSON string of request trace information

func (TraceInfo) String ¶

func (ti TraceInfo) String() string

String method returns string representation of request trace information.

func (*WeightedRoundRobin) Close ¶

func (wrr *WeightedRoundRobin) Close() error

Close method does the cleanup by stopping the time.Ticker on Weighted Round-Robin(WRR) request load balancer

func (*WeightedRoundRobin) Feedback ¶

func (wrr *WeightedRoundRobin) Feedback(f *RequestFeedback)

Feedback method process the request feedback for Weighted Round-Robin(WRR) request load balancer

func (*WeightedRoundRobin) Next ¶

func (wrr *WeightedRoundRobin) Next() (string, error)

Next method returns the next Base URL based on Weighted Round-Robin(WRR)

func (*WeightedRoundRobin) Refresh ¶

func (wrr *WeightedRoundRobin) Refresh(hosts ...*Host) error

Refresh method reset the existing values with the given Host slice to refresh it

func (*WeightedRoundRobin) SetOnStateChange ¶

func (wrr *WeightedRoundRobin) SetOnStateChange(fn HostStateChangeFunc)

SetOnStateChange method used to set a callback for the host transition state

func (*WeightedRoundRobin) SetRecoveryDuration ¶

func (wrr *WeightedRoundRobin) SetRecoveryDuration(d time.Duration)

SetRecoveryDuration method is used to change the existing recovery duration for the host