restclient

README

This is a simple http client package with validation. It makes use of github.com/go-playground/validator as well as the github.com/google/go-querystring packages.

Documentation

Index

• type BaseClient
  • func (bc *BaseClient) Delete(ctx context.Context, path string, queryStruct interface{}, ...) error
  • func (bc *BaseClient) Get(ctx context.Context, path string, queryStruct interface{}, ...) error
  • func (bc *BaseClient) Post(ctx context.Context, path string, queryStruct, requestBody interface{}, ...) error
  • func (bc *BaseClient) Put(ctx context.Context, path string, queryStruct, requestBody interface{}, ...) error
  • func (bc *BaseClient) Req(ctx context.Context, method, path string, queryStruct, requestBody interface{}, ...) (*http.Response, error)
• type Client
  • func NewClient(cfg *ClientConfig, transport http.RoundTripper) (*Client, error)
  • func (cl *Client) Delete(ctx context.Context, baseURL *url.URL, path string, queryStruct interface{}, ...) error
  • func (cl *Client) Get(ctx context.Context, baseURL *url.URL, path string, queryStruct interface{}, ...) error
  • func (cl *Client) Post(ctx context.Context, baseURL *url.URL, path string, ...) error
  • func (cl *Client) Put(ctx context.Context, baseURL *url.URL, path string, ...) error
  • func (cl *Client) Req(ctx context.Context, baseURL *url.URL, method, path string, ...) (*http.Response, error)
• type ClientConfig
• type CustomDecoder
• type Duration
  • func (d Duration) MarshalText() ([]byte, error)
  • func (d *Duration) UnmarshalText(text []byte) error
• type ErrorResponseCallback
• type FixupCallback
• type ResponseError
  • func (rs *ResponseError) Error() string

Types

type BaseClient

type BaseClient struct {
	Client  *Client
	BaseURL *url.URL
}

BaseClient - convenience wrapper for requests that all go to the same BaseURL.

func (*BaseClient) Delete

func (bc *BaseClient) Delete(ctx context.Context, path string, queryStruct interface{}, responseBody interface{}) error

Delete - like Client.Delete, except uses BaseClient.BaseURL instead of needing to be passed in.

func (*BaseClient) Get

func (bc *BaseClient) Get(ctx context.Context, path string, queryStruct interface{}, responseBody interface{}) error

Get - like Client.Get, except uses the BaseClient.BaseURL instead of needing to be passed in.

func (*BaseClient) Post

func (bc *BaseClient) Post(ctx context.Context, path string, queryStruct, requestBody interface{}, responseBody interface{}) error

Post - like Client.Post, except uses BaseClient.BaseURL instead of needing to be passed in.

func (*BaseClient) Put

func (bc *BaseClient) Put(ctx context.Context, path string, queryStruct, requestBody interface{}, responseBody interface{}) error

Put - like Client.Put, except uses BaseClient.BaseURL instead of needing to be passed in.

func (*BaseClient) Req

func (bc *BaseClient) Req(ctx context.Context, method, path string, queryStruct,
	requestBody interface{}, responseBody interface{}) (*http.Response, error)

Req - like Client.Req, except uses BaseClient.BaseURL instead of needing to be passed in.

type Client

type Client struct {
	Client *http.Client

	// Specifying this allows you to modify headers, add
	// auth tokens or signatures etc before the request is sent.
	FixupCallback FixupCallback

	// ErrorResponseCallback - allows you to specify custom behavior
	// on responses that are >= 400 status code.
	ErrorResponseCallback ErrorResponseCallback

	// StripBOM - setting this to true gives you the option to strip
	// byte order markings from certain responses.
	StripBOM bool

	// FormEncodedBody - setting this to true uses x-www-form-urlencoded.
	// false (default) will do json encoding.
	FormEncodedBody bool

	// SkipValidate - setting this to true bypasses validator run.
	SkipValidate bool
	// contains filtered or unexported fields
}

Client - admin api struct

func NewClient

func NewClient(cfg *ClientConfig, transport http.RoundTripper) (*Client, error)

NewClient - Client factory method. - if transport is nil, build one using config data in cfg. This is optional, you can also initialize the following way:

cl := &restclient.Client{Client: &http.Client{}}

func (*Client) Delete

func (cl *Client) Delete(ctx context.Context, baseURL *url.URL, path string, queryStruct interface{}, responseBody interface{}) error

Delete - makes an http DELETE request to baseURL with path appended, and queryStruct optionally parsed by go-querystring and validated with go-playground/validator.v9. Upon successful request, response is unmarshaled as json into responseBody, unless responseBody implements CustomDecoder, in which case Decode() is called.

func (*Client) Get

func (cl *Client) Get(ctx context.Context, baseURL *url.URL, path string, queryStruct interface{}, responseBody interface{}) error

Get - makes an http GET request to baseURL with path appended, and queryStruct optionally parsed by go-querystring and validated with go-playground/validator.v9. Upon successful request, response is unmarshaled as json into responseBody, unless responseBody implements CustomDecoder, in which case Decode() is called.

func (*Client) Post

func (cl *Client) Post(ctx context.Context, baseURL *url.URL, path string, queryStruct, requestBody interface{}, responseBody interface{}) error

Post - makes an http POST request to baseURL with path appended, and queryStruct optionally parsed by go-querystring and validated with go-playground/validator.v9. requestBody is passed to go-playground/validator.v9 and is sent json-encoded as the body. Upon successful request, response is unmarshaled as json into responseBody, unless responseBody implements CustomDecoder, in which case Decode() is called.

func (*Client) Put

func (cl *Client) Put(ctx context.Context, baseURL *url.URL, path string, queryStruct, requestBody interface{}, responseBody interface{}) error

Put - makes an http PUT request to baseURL with path appended, and queryStruct optionally parsed by go-querystring and validated with go-playground/validator.v9. requestBody is passed to go-playground/validator.v9 and is sent json-encoded as the body. Upon successful request, response is unmarshaled as json into responseBody, unless responseBody implements CustomDecoder, in which case Decode() is called.

func (*Client) Req

func (cl *Client) Req(ctx context.Context, baseURL *url.URL, method, path string,
	queryStruct, requestBody, responseBody interface{}) (*http.Response, error)

Req - like the method-specific versions above, this is the general purpose. the *http.Response return value will either be nil or return with the Body closed and fully read. This is mainly useful for inspecting headers, status code etc.

type ClientConfig

type ClientConfig struct {
	ClientTimeout      Duration
	CACertBundlePath   string
	CACertBundle       []byte
	InsecureSkipVerify bool
	Expiration         time.Time
	RawValidatorErrors bool // If true, then no attempt to interpret validator errors will be made.

	// FixupCallback - this is a method that will get called before every request
	// so that you can, for instance, manipulate headers for auth purposes, for
	// instance.
	FixupCallback FixupCallback
}

ClientConfig - this configures an Client.

Specify CACertBundlePath to load a bundle from disk to override the default. Specify CACertBundle if you want embed the cacert bundle in PEM format. Specify one or the other if you want to override, or neither to use the default. If both are specified, CACertBundle is honored.

type CustomDecoder

type CustomDecoder interface {
	Decode(data io.Reader) error
}

CustomDecoder - If a response struct implements this interface, calls the Decode() method instead of json.Unmarshal.

type Duration

type Duration time.Duration

Duration - this allows us to use a text representation of a duration and have it parse correctly. The go standard library time.Duration does not implement the TextUnmarshaller interface, so we have to do this workaround in order for json.Unmarshal or external parsers like toml.Decode to work with human friendly input.

func (Duration) MarshalText

func (d Duration) MarshalText() ([]byte, error)

MarshalText - this implements TextMarshaler

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

UnmarshalText - this implements the TextUnmarshaler interface

type ErrorResponseCallback

type ErrorResponseCallback func(resp *http.Response) error

ErrorResponseCallback - this allows you to hook into the error response, for response codes that are >= 400. If error returned here is nil, processing continues. Otherwise, the error returned is bubbled to caller.

type FixupCallback

type FixupCallback func(req *http.Request) error

FixupCallback - this is a method that will get called before every request so that you can, for instance, manipulate headers for auth purposes, for instance.

type ResponseError

type ResponseError struct {
	Status       string
	StatusCode   int
	ResponseBody []byte
	Header       http.Header
}

func (*ResponseError) Error

func (rs *ResponseError) Error() string