rest

Documentation

Overview

Package rest implements a simple REST wrapper

All methods are safe for concurrent calling.

Index

• func ClientWithHeaderReset(c *http.Client, headers map[string]string) *http.Client
• func DecodeJSON(resp *http.Response, result interface{}) (err error)
• func DecodeXML(resp *http.Response, result interface{}) (err error)
• func MultipartUpload(in io.Reader, params url.Values, contentName, fileName string) (io.ReadCloser, string, error)
• func ReadBody(resp *http.Response) (result []byte, err error)
• func URLEscape(in string) string
• func URLJoin(base *url.URL, path string) (*url.URL, error)
• type Client
  • func NewClient(c *http.Client) *Client
  • func (api *Client) Call(opts *Opts) (resp *http.Response, err error)
  • func (api *Client) CallJSON(opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)
  • func (api *Client) CallXML(opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)
  • 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 ClientWithHeaderReset

func ClientWithHeaderReset(c *http.Client, headers map[string]string) *http.Client

ClientWithHeaderReset makes a new http client which resets the headers passed in on redirect

FIXME This is now unecessary with go1.8

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(in io.Reader, params url.Values, contentName, fileName string) (io.ReadCloser, string, 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 params - the form parameters fileName - is the name of the attached file contentName - the name of the parameter for the file

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

func ReadBody

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

ReadBody reads resp.Body into result, closing the body

func URLEscape

func URLEscape(in string) string

URLEscape escapes URL path the in string using URL escaping rules

This mimics url.PathEscape which only available from go 1.8

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

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(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

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

func (*Client) CallJSON

func (api *Client) CallJSON(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 (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 MultpartContentName 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(opts *Opts, request interface{}, response interface{}) (resp *http.Response, err error)

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

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

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) 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

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
	NoResponse            bool // set to close Body
	ContentType           string
	ContentLength         *int64
	ContentRange          string
	ExtraHeaders          map[string]string
	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
	Close                 bool       // set to close the connection after this transaction
}

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