Documentation ¶
Overview ¶
Package requests implements a friendly API over Go's existing net/http library
Index ¶
- Variables
- func BuildHTTPClient(ro RequestOptions) *http.Client
- func EnsureTransporterFinalized(httpTransport *http.Transport)
- type FileUpload
- type RequestOptions
- type Response
- func Delete(url string, ro *RequestOptions) *Response
- func Get(url string, ro *RequestOptions) *Response
- func Head(url string, ro *RequestOptions) *Response
- func Options(url string, ro *RequestOptions) *Response
- func Patch(url string, ro *RequestOptions) *Response
- func Post(url string, ro *RequestOptions) *Response
- func Put(url string, ro *RequestOptions) *Response
- func SendRequest(method, url string, ro *RequestOptions) *Response
- func (r *Response) Bytes() []byte
- func (r *Response) ClearInternalBuffer()
- func (r *Response) Close() error
- func (r *Response) DownloadToFile(fileName string) error
- func (r *Response) JSON(userStruct interface{}) error
- func (r *Response) Read(p []byte) (n int, err error)
- func (r *Response) String() string
- func (r *Response) XML(userStruct interface{}, charsetReader XMLCharDecoder) error
- type Session
- func (s *Session) CloseIdleConnections()
- func (s *Session) Delete(url string, ro *RequestOptions) *Response
- func (s *Session) Get(url string, ro *RequestOptions) *Response
- func (s *Session) Head(url string, ro *RequestOptions) *Response
- func (s *Session) Options(url string, ro *RequestOptions) *Response
- func (s *Session) Patch(url string, ro *RequestOptions) *Response
- func (s *Session) Post(url string, ro *RequestOptions) *Response
- func (s *Session) Put(url string, ro *RequestOptions) *Response
- type XMLCharDecoder
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRedirectLimitExceeded is the error returned when the request responded // with too many redirects ErrRedirectLimitExceeded = errors.New("requests: Request exceeded redirect count") // RedirectLimit is a tunable variable that specifies how many times we can // redirect in response to a redirect. This is the global variable, if you // wish to set this on a request by request basis, set it within the // `RequestOptions` structure RedirectLimit = 30 // SensitiveHTTPHeaders is a map of sensitive HTTP headers that a user // doesn't want passed on a redirect. This is the global variable, if you // wish to set this on a request by request basis, set it within the // `RequestOptions` structure SensitiveHTTPHeaders = map[string]struct{}{ "Www-Authenticate": {}, "Authorization": {}, "Proxy-Authorization": {}, } )
Functions ¶
func BuildHTTPClient ¶
func BuildHTTPClient(ro RequestOptions) *http.Client
BuildHTTPClient is a function that will return a custom HTTP client based on the request options provided the check is in UseDefaultClient
func EnsureTransporterFinalized ¶
EnsureTransporterFinalized will ensure that when the HTTP client is GCed the runtime will close the idle connections (so that they won't leak) this function was adopted from Hashicorp's go-cleanhttp package
Types ¶
type FileUpload ¶
type FileUpload struct { // Filename is the name of the file that you wish to upload. We use this to guess the mimetype as well as pass it onto the server FileName string // FileContents is happy as long as you pass it a io.ReadCloser (which most file use anyways) FileContents io.ReadCloser // FieldName is form field name FieldName string // FileMime represents which mimetime should be sent along with the file. // When empty, defaults to application/octet-stream FileMime string }
FileUpload is a struct that is used to specify the file that a User wishes to upload.
type RequestOptions ¶
type RequestOptions struct { Headers map[string]string Data map[string]string Params map[string]string Files map[string]string Cookies map[string]string // QueryStruct is a struct that encapsulates a set of URL query params // this paramter is mutually exclusive with `Params map[string]string` (they cannot be combined) // for more information please see https://godoc.org/github.com/google/go-querystring/query QueryStruct interface{} // Files is where you can include files to upload. The use of this data // structure is limited to POST requests FileUploads []FileUpload // JSON can be used when you wish to send JSON within the request body JSON interface{} // XML can be used if you wish to send XML within the request body XML interface{} // InsecureSkipVerify is a flag that specifies if we should validate the // server's TLS certificate. It should be noted that Go's TLS verify mechanism // doesn't validate if a certificate has been revoked InsecureSkipVerify bool // DisableCompression will disable gzip compression on requests DisableCompression bool // UserAgent allows you to set an arbitrary custom user agent UserAgent string // Host allows you to set an arbitrary custom host Host string // Auth allows you to specify a user name and password that you wish to // use when requesting the URL. It will use basic HTTP authentication // formatting the username and password in base64 the format is: // []string{username, password} Auth []string // IsAjax is a flag that can be set to make the request appear // to be generated by browser Javascript IsAjax bool // UseCookieJar will create a custom HTTP client that will // process and store HTTP cookies when they are sent down UseCookieJar bool // Proxies is a map in the following format // *protocol* => proxy address e.g http => http://127.0.0.1:8080 Proxies map[string]*url.URL // TLSHandshakeTimeout specifies the maximum amount of time waiting to // wait for a TLS handshake. Zero means no timeout. TLSHandshakeTimeout time.Duration // DialTimeout is the maximum amount of time a dial will wait for // a connect to complete. DialTimeout time.Duration // KeepAlive specifies the keep-alive period for an active // network connection. If zero, keep-alive are not enabled. DialKeepAlive time.Duration // RequestTimeout is the maximum amount of time a whole request(include dial / request / redirect) // will wait. RequestTimeout time.Duration // HTTPClient can be provided if you wish to supply a custom HTTP client // this is useful if you want to use an OAUTH client with your request. HTTPClient *http.Client // SensitiveHTTPHeaders is a map of sensitive HTTP headers that a user // doesn't want passed on a redirect. SensitiveHTTPHeaders map[string]struct{} // RedirectLimit is the acceptable amount of redirects that we should expect // before returning an error be default this is set to 30. You can change this // globally by modifying the `RedirectLimit` variable. RedirectLimit int // RequestBody allows you to put anything matching an `io.Reader` into the request // this option will take precedence over any other request option specified RequestBody io.Reader // CookieJar allows you to specify a special cookiejar to use with your request. // this option will take precedence over the `UseCookieJar` option above. CookieJar http.CookieJar // Context can be used to maintain state between requests https://golang.org/pkg/context/#Context Context context.Context // BeforeRequest is a hook that can be used to modify the request object // before the request has been fired. This is useful for adding authentication // and other functionality not provided in this library BeforeRequest func(req *http.Request) error // LocalAddr allows you to send the request on any local interface LocalAddr *net.TCPAddr }
RequestOptions is the location that of where the data
type Response ¶
type Response struct { // Ok is a boolean flag that validates that the server returned a 2xx code Ok bool // This is the Go error flag – if something went wrong within the request, this flag will be set. Error error // We want to abstract (at least at the moment) the Go http.Response object away. So we are going to make use of it // internal but not give the user access RawResponse *http.Response // StatusCode is the HTTP Status Code returned by the HTTP Response. Taken from resp.StatusCode StatusCode int // Header is a net/http/Header structure Header http.Header // contains filtered or unexported fields }
Response is what is returned to a user when they fire off a request
func Delete ¶
func Delete(url string, ro *RequestOptions) *Response
Delete takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func Get ¶
func Get(url string, ro *RequestOptions) *Response
Get takes 2 parameters and returns a Response Struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func Head ¶
func Head(url string, ro *RequestOptions) *Response
Head takes 2 parameters and returns a Response channel. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func Options ¶
func Options(url string, ro *RequestOptions) *Response
Options takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func Patch ¶
func Patch(url string, ro *RequestOptions) *Response
Patch takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func Post ¶
func Post(url string, ro *RequestOptions) *Response
Post takes 2 parameters and returns a Response channel. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func Put ¶
func Put(url string, ro *RequestOptions) *Response
Put takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
func SendRequest ¶
func SendRequest(method, url string, ro *RequestOptions) *Response
SendRequest adds generic test functionality
func (*Response) ClearInternalBuffer ¶
func (r *Response) ClearInternalBuffer()
ClearInternalBuffer is a function that will clear the internal buffer that we use to hold the .String() and .Bytes() data. Once you have used these functions – you may want to free up the memory.
func (*Response) Close ¶
Close is part of our ability to support io.ReadCloser if someone wants to make use of the raw body
func (*Response) DownloadToFile ¶
DownloadToFile allows you to download the contents of the response to a file
func (*Response) JSON ¶
JSON is a method that will populate a struct that is provided `userStruct` with the JSON returned within the response body
func (*Response) Read ¶
Read is part of our ability to support io.ReadCloser if someone wants to make use of the raw body
func (*Response) XML ¶
func (r *Response) XML(userStruct interface{}, charsetReader XMLCharDecoder) error
XML is a method that will populate a struct that is provided `userStruct` with the XML returned within the response body
type Session ¶
type Session struct { // RequestOptions is global options RequestOptions *RequestOptions // HTTPClient is the client that we will use to request the resources HTTPClient *http.Client }
Session allows a user to make use of persistent cookies in between HTTP requests
func NewSession ¶
func NewSession(ro *RequestOptions) *Session
NewSession returns a session struct which enables can be used to maintain establish a persistent state with the server This function will set UseCookieJar to true as that is the purpose of using the session
func (*Session) CloseIdleConnections ¶
func (s *Session) CloseIdleConnections()
CloseIdleConnections closes the idle connections that a session client may make use of
func (*Session) Delete ¶
func (s *Session) Delete(url string, ro *RequestOptions) *Response
Delete takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
func (*Session) Get ¶
func (s *Session) Get(url string, ro *RequestOptions) *Response
Get takes 2 parameters and returns a Response Struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
func (*Session) Head ¶
func (s *Session) Head(url string, ro *RequestOptions) *Response
Head takes 2 parameters and returns a Response channel. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
func (*Session) Options ¶
func (s *Session) Options(url string, ro *RequestOptions) *Response
Options takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
func (*Session) Patch ¶
func (s *Session) Patch(url string, ro *RequestOptions) *Response
Patch takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
func (*Session) Post ¶
func (s *Session) Post(url string, ro *RequestOptions) *Response
Post takes 2 parameters and returns a Response channel. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
func (*Session) Put ¶
func (s *Session) Put(url string, ro *RequestOptions) *Response
Put takes 2 parameters and returns a Response struct. These two options are:
- A URL
- A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct
type XMLCharDecoder ¶
XMLCharDecoder is a helper type that takes a stream of bytes (not encoded in UTF-8) and returns a reader that encodes the bytes into UTF-8. This is done because Go's XML library only supports XML encoded in UTF-8