rest

Documentation

Overview

Package rest implements a simple REST wrapper

All methods are safe for concurrent calling.

Index

• func ClientWithNoRedirects(c *http.Client) *http.Client
• func DecodeJSON(resp *http.Response, result interface{}) (err error)
• func DecodeXML(resp *http.Response, result interface{}) (err error)
• func MultipartUpload(ctx context.Context, in io.Reader, params url.Values, ...) (io.ReadCloser, string, int64, error)
• func ParseSizeFromHeaders(headers http.Header) (size int64)
• func ReadBody(resp *http.Response) (result []byte, err error)
• func URLJoin(base *url.URL, path string) (*url.URL, error)
• func URLPathEscape(in string) string
• type Client
  • func NewClient(c *http.Client) *Client
  • func (api *Client) Call(ctx context.Context, opts *Opts) (resp *http.Response, err error)
  • func (api *Client) CallJSON(ctx context.Context, opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)
  • func (api *Client) CallXML(ctx context.Context, opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)
  • func (api *Client) Do(req *http.Request) (*http.Response, error)
  • func (api *Client) RemoveHeader(key string) *Client
  • func (api *Client) SetCookie(cks ...*http.Cookie) *Client
  • func (api *Client) SetErrorHandler(fn func(resp *http.Response) error) *Client
  • func (api *Client) SetHeader(key, value string) *Client
  • func (api *Client) SetRoot(RootURL string) *Client
  • func (api *Client) SetSigner(signer SignerFn) *Client
  • func (api *Client) SetUserPass(UserName, Password string) *Client
• type Opts
  • func (o *Opts) Copy() *Opts
• type SignerFn

Functions

func ClientWithNoRedirects

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

ClientWithNoRedirects makes a new http client which won't follow redirects

func DecodeJSON

func DecodeJSON(resp *http.Response, result interface{}) (err error)

DecodeJSON decodes resp.Body into result

func DecodeXML

func DecodeXML(resp *http.Response, result interface{}) (err error)

DecodeXML decodes resp.Body into result

func MultipartUpload

func MultipartUpload(ctx context.Context, in io.Reader, params url.Values, contentName, fileName string) (io.ReadCloser, string, int64, error)

MultipartUpload creates an io.Reader which produces an encoded a multipart form upload from the params passed in and the passed in

in - the body of the file (may be nil) params - the form parameters fileName - is the name of the attached file contentName - the name of the parameter for the file

the int64 returned is the overhead in addition to the file contents, in case Content-Length is required

NB This doesn't allow setting the content type of the attachment

func ParseSizeFromHeaders

func ParseSizeFromHeaders(headers http.Header) (size int64)

ParseSizeFromHeaders parses HTTP response headers to get the full file size. Returns -1 if the headers did not exist or were invalid.

func ReadBody

func ReadBody(resp *http.Response) (result []byte, err error)

ReadBody reads resp.Body into result, closing the body

func URLJoin

func URLJoin(base *url.URL, path string) (*url.URL, error)

URLJoin joins a URL and a path returning a new URL

path should be URL escaped

func URLPathEscape

func URLPathEscape(in string) string

URLPathEscape escapes URL path the in string using URL escaping rules

This mimics url.PathEscape which only available from go 1.8

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client contains the info to sustain the API

func NewClient

func NewClient(c *http.Client) *Client

NewClient takes an oauth http.Client and makes a new api instance

func (*Client) Call

func (api *Client) Call(ctx context.Context, opts *Opts) (resp *http.Response, err error)

Call makes the call and returns the http.Response

if err == nil then resp.Body will need to be closed unless opt.NoResponse is set

if err != nil then resp.Body will have been closed

it will return resp if at all possible, even if err is set

func (*Client) CallJSON

func (api *Client) CallJSON(ctx context.Context, opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)

CallJSON runs Call and decodes the body as a JSON object into response (if not nil)

If request is not nil then it will be JSON encoded as the body of the request.

If response is not nil then the response will be JSON decoded into it and resp.Body will be closed.

If response is nil then the resp.Body will be closed only if opts.NoResponse is set.

If (opts.MultipartParams or opts.MultipartContentName) and opts.Body are set then CallJSON will do a multipart upload with a file attached. opts.MultipartContentName is the name of the parameter and opts.MultipartFileName is the name of the file. If MultipartContentName is set, and request != nil is supplied, then the request will be marshalled into JSON and added to the form with parameter name MultipartMetadataName.

It will return resp if at all possible, even if err is set

func (*Client) CallXML

func (api *Client) CallXML(ctx context.Context, opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)

CallXML runs Call and decodes the body as an XML object into response (if not nil)

If request is not nil then it will be XML encoded as the body of the request.

If response is not nil then the response will be XML decoded into it and resp.Body will be closed.

If response is nil then the resp.Body will be closed only if opts.NoResponse is set.

See CallJSON for a description of MultipartParams and related opts.

It will return resp if at all possible, even if err is set

func (*Client) Do

func (api *Client) Do(req *http.Request) (*http.Response, error)

Do calls the internal http.Client.Do method

func (*Client) RemoveHeader

func (api *Client) RemoveHeader(key string) *Client

RemoveHeader unsets a header for all requests

func (*Client) SetCookie

func (api *Client) SetCookie(cks ...*http.Cookie) *Client

SetCookie creates a Cookies Header for all requests with the supplied cookies passed in. All cookies have to be supplied at once, all cookies will be overwritten on a new call to the method

func (*Client) SetErrorHandler

func (api *Client) SetErrorHandler(fn func(resp *http.Response) error) *Client

SetErrorHandler sets the handler to decode an error response when the HTTP status code is not 2xx. The handler should close resp.Body.

func (*Client) SetHeader

func (api *Client) SetHeader(key, value string) *Client

SetHeader sets a header for all requests Start the key with "*" for don't canonicalise

func (*Client) SetRoot

func (api *Client) SetRoot(RootURL string) *Client

SetRoot sets the default RootURL. You can override this on a per call basis using the RootURL field in Opts.

func (*Client) SetSigner

func (api *Client) SetSigner(signer SignerFn) *Client

SetSigner sets a signer for all requests

func (*Client) SetUserPass

func (api *Client) SetUserPass(UserName, Password string) *Client

SetUserPass creates an Authorization header for all requests with the UserName and Password passed in

type Opts

type Opts struct {
	Method                string // GET, POST, etc.
	Path                  string // relative to RootURL
	RootURL               string // override RootURL passed into SetRoot()
	Body                  io.Reader
	GetBody               func() (io.ReadCloser, error) // body builder, needed to enable low-level HTTP/2 retries
	NoResponse            bool                          // set to close Body
	ContentType           string
	ContentLength         *int64
	ContentRange          string
	ExtraHeaders          map[string]string // extra headers, start them with "*" for don't canonicalise
	UserName              string            // username for Basic Auth
	Password              string            // password for Basic Auth
	Options               []fs.OpenOption
	IgnoreStatus          bool         // if set then we don't check error status or parse error body
	MultipartParams       url.Values   // if set do multipart form upload with attached file
	MultipartMetadataName string       // ..this is used for the name of the metadata form part if set
	MultipartContentName  string       // ..name of the parameter which is the attached file
	MultipartFileName     string       // ..name of the file for the attached file
	Parameters            url.Values   // any parameters for the final URL
	TransferEncoding      []string     // transfer encoding, set to "identity" to disable chunked encoding
	Trailer               *http.Header // set the request trailer
	Close                 bool         // set to close the connection after this transaction
	NoRedirect            bool         // if this is set then the client won't follow redirects
	// On Redirects, call this function - see the http.Client docs: https://pkg.go.dev/net/http#Client
	CheckRedirect func(req *http.Request, via []*http.Request) error
}

Opts contains parameters for Call, CallJSON, etc.

func (*Opts) Copy

func (o *Opts) Copy() *Opts

Copy creates a copy of the options

type SignerFn

type SignerFn func(*http.Request) error

SignerFn is used to sign an outgoing request