From 95479cff2565825024f729ad06a849564589259e Mon Sep 17 00:00:00 2001 From: lucperkins Date: Mon, 4 May 2020 23:54:27 -0700 Subject: [PATCH] Add missing API docs --- errors.go | 1 + methods.go | 20 +++++++++++++------- options.go | 49 ++++++++++++++++++++++++++++++------------------- response.go | 21 +++++++++++++++++++++ 4 files changed, 65 insertions(+), 26 deletions(-) diff --git a/errors.go b/errors.go index dc894d3..86cf24b 100644 --- a/errors.go +++ b/errors.go @@ -2,4 +2,5 @@ package rek import "errors" +// The error thrown when you attempt to set the HTTP request body more than once var ErrRequestBodySetMultipleTimes = errors.New("you have set the request body more than once") diff --git a/methods.go b/methods.go index 2920492..bad5e77 100644 --- a/methods.go +++ b/methods.go @@ -2,27 +2,33 @@ package rek import "net/http" -func Get(url string, opts ...Option) (*Response, error) { +// GET request +func Get(url string, opts ...option) (*Response, error) { return call(http.MethodGet, url, opts...) } -func Post(url string, opts ...Option) (*Response, error) { +// POST request +func Post(url string, opts ...option) (*Response, error) { return call(http.MethodPost, url, opts...) } -func Put(url string, opts ...Option) (*Response, error) { +// PUT request +func Put(url string, opts ...option) (*Response, error) { return call(http.MethodPut, url, opts...) } -func Delete(url string, opts ...Option) (*Response, error) { +// DELETE request +func Delete(url string, opts ...option) (*Response, error) { return call(http.MethodDelete, url, opts...) } -func Patch(url string, opts ...Option) (*Response, error) { +// PATCH request +func Patch(url string, opts ...option) (*Response, error) { return call(http.MethodPatch, url, opts...) } -func Head(url string, opts ...Option) (*Response, error) { +// HEAD request +func Head(url string, opts ...option) (*Response, error) { options, err := buildOptions(opts...) cl := makeClient(options) @@ -35,7 +41,7 @@ func Head(url string, opts ...Option) (*Response, error) { return makeResponse(res) } -func call(method, url string, opts ...Option) (*Response, error) { +func call(method, url string, opts ...option) (*Response, error) { options, err := buildOptions(opts...) if err != nil { return nil, err diff --git a/options.go b/options.go index 674149b..37311ee 100644 --- a/options.go +++ b/options.go @@ -41,6 +41,7 @@ func (o *options) validate() error { i++ } + // Throw an error if the request body has been set more than once. if i > 1 { return ErrRequestBodySetMultipleTimes } @@ -48,64 +49,75 @@ func (o *options) validate() error { return nil } -type Option func(*options) +type option func(*options) -func Headers(headers map[string]string) Option { +// Add headers to the request. +func Headers(headers map[string]string) option { return func(opts *options) { opts.headers = headers } } -func Timeout(timeout time.Duration) Option { +// Add a timeout to the request. +func Timeout(timeout time.Duration) option { return func(opts *options) { opts.timeout = timeout } } -func BasicAuth(username, password string) Option { +// Add a basic auth username and password to the request. +func BasicAuth(username, password string) option { return func(opts *options) { opts.username = username opts.password = password } } -func Data(data interface{}) Option { +// Add any interface{} that can be serialized to a []byte and apply a "Content-Type: application/octet-stream" header. +func Data(data interface{}) option { return func(opts *options) { opts.data = data } } -func UserAgent(agent string) Option { +// Add a User-Agent header to the request. +func UserAgent(agent string) option { return func(opts *options) { opts.userAgent = agent } } -func Json(v interface{}) Option { +// Add any interface{} that can be marshaled as JSON to the request body and apply a "Content-Type: +// application/json;charset=utf-8" header. +func Json(v interface{}) option { return func(opts *options) { opts.jsonObj = v } } -func Callback(cb func(*Response)) Option { +// Add a callback function for handling the Response. +func Callback(cb func(*Response)) option { return func(opts *options) { opts.callback = cb } } -func Cookies(cookies []*http.Cookie) Option { +// Add cookies to the request. +func Cookies(cookies []*http.Cookie) option { return func(opts *options) { opts.cookies = cookies } } -func CookieJar(jar http.CookieJar) Option { +// Add a cookie jar to the request. +func CookieJar(jar http.CookieJar) option { return func(opts *options) { opts.cookieJar = &jar } } -func File(fieldName, filepath string, params map[string]string) Option { +// Create a multipart file upload request. +func File(fieldName, filepath string, params map[string]string) option { return func(opts *options) { opts.file = &file{ FieldName: fieldName, @@ -115,25 +127,28 @@ func File(fieldName, filepath string, params map[string]string) Option { } } -func FormData(form map[string]string) Option { +// Add key/value form data to the request body and apply a "Content-Type: application/x-www-form-urlencoded" header. +func FormData(form map[string]string) option { return func(opts *options) { opts.formData = form } } -func Bearer(bearer string) Option { +// Add a bearer header of the form "Authorization: Bearer ..." +func Bearer(bearer string) option { return func(opts *options) { opts.bearer = bearer } } -func DisallowRedirects() Option { +// Turn redirects off. +func DisallowRedirects() option { return func(opts *options) { opts.disallowRedirects = true } } -func buildOptions(opts ...Option) (*options, error) { +func buildOptions(opts ...option) (*options, error) { os := &options{ headers: nil, timeout: 10 * time.Second, @@ -169,10 +184,6 @@ func setHeaders(req *http.Request, opts *options) *http.Request { req.Header.Set("Content-Type", "application/octet-stream") } - if opts.jsonObj != nil { - req.Header.Set("Content-Type", "application/json; charset=utf-8") - } - if opts.formData != nil { req.Header.Set("Content-Type", "application/x-www-form-urlencoded") } diff --git a/response.go b/response.go index 40b2c66..467606e 100644 --- a/response.go +++ b/response.go @@ -1,10 +1,12 @@ package rek import ( + "encoding/json" "io/ioutil" "net/http" ) +// A struct containing the relevant response information returned by a rek request. type Response struct { statusCode int content []byte @@ -52,38 +54,57 @@ func makeResponse(res *http.Response) (*Response, error) { return resp, nil } +// The status code of the response (200, 404, etc.) func (r *Response) StatusCode() int { return r.statusCode } +// The response body as raw bytes. func (r *Response) Content() []byte { return r.content } +// The headers associated with the response. func (r *Response) Headers() map[string]string { return r.headers } +// The response's encoding. func (r *Response) Encoding() []string { return r.encoding } +// The response body as a string. func (r *Response) Text() string { return string(r.content) } +// Marshal a JSON response body. +func (r *Response) Json(v interface{}) error { + return json.Unmarshal(r.content, v) +} + +// The Content-Type header for the request (if any). +func (r *Response) ContentType() string { + return r.Headers()["Content-Type"] +} + +// The raw *http.Response returned by the operation. func (r *Response) Raw() *http.Response { return r.res } +// The cookies associated with the response. func (r *Response) Cookies() []*http.Cookie { return r.cookies } +// The content length of the response body. func (r *Response) ContentLength() int64 { return r.res.ContentLength } +// The response's status, e.g. "200 OK." func (r *Response) Status() string { return r.res.Status }