restclient

Documentation

Overview

Package restclient wraps a REST-ful web service to expose objects from the service in Go programs. Construct a client using restclient.New("http://service.com/api/endpoint"). Use the client's HTTP-verb methods to receive the result of REST operations in a Go type. For example, to get a collection of Items, invoke client.Get("items", m) where m is of type []Item.

The package also exposes lower level interfaces to receive the raw http.Response from the client and to construct requests to a client's service that may be sent later, or by an alternate client or transport.

Index

• Constants
• type Client
  • func New(baseurl string) (*Client, error)
  • func NewDisableKeepAlives(baseurl string) (*Client, error)
  • func (c *Client) BaseURL() *url.URL
  • func (c *Client) Delete(endpoint string, resp interface{}) error
  • func (c *Client) Do(req *Request) (*http.Response, error)
  • func (c *Client) Get(endpoint string, resp interface{}) error
  • func (c *Client) NewFormRequest(method Method, endpoint string, params map[string]string) *Request
  • func (c *Client) NewJsonRequest(method Method, endpoint string, obj interface{}) (req *Request)
  • func (c *Client) NewRequest(method Method, endpoint string, ctype string, body io.Reader) (req *Request)
  • func (c *Client) Post(endpoint string, req interface{}, resp interface{}) error
  • func (c *Client) Put(endpoint string, req interface{}, resp interface{}) error
  • func (c *Client) Result(req *Request, resp interface{}) error
  • func (c *Client) SetAccessToken(token string)
  • func (c *Client) SetTimeout(duration time.Duration)
• type Method
• type Request
  • func (r *Request) HTTPRequest() (*http.Request, error)
• type RestError
  • func (r *RestError) Body() string
  • func (r *RestError) Error() string

Constants

const (
	GET    = Method("GET")
	POST   = Method("POST")
	PUT    = Method("PUT")
	DELETE = Method("DELETE")
)

HTTP methods for REST

Types

type Client

type Client struct {
	// Driver is the *http.Client that performs requests.
	Driver *http.Client

	// Headers represents common headers that are added to each request.
	Headers http.Header
	// KeepAlives enabled
	KeepAlives bool
	// contains filtered or unexported fields
}

Client represents a client bound to a given REST base URL.

func New

func New(baseurl string) (*Client, error)

New returns a *Client with the specified base URL endpoint, expected to include the port string and any path, if required. Returns an error if baseurl cannot be parsed as an absolute URL.

func NewDisableKeepAlives

func NewDisableKeepAlives(baseurl string) (*Client, error)

NewWithoutKeepAlives returns a new client with keepalives disabled.

func (*Client) BaseURL

func (c *Client) BaseURL() *url.URL

BaseURL returns a *url.URL to a copy of Client's base so the caller may modify it.

func (*Client) Delete

func (c *Client) Delete(endpoint string, resp interface{}) error

Delete issues a DELETE request to the specified endpoint and parses the response in to resp. It will return an error if it failed to send the request, a *RestError if the response wasn't a 2xx status code, or an error from package json's Decode.

func (*Client) Do

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

Do performs the HTTP request described by req and returns the *http.Response. Also returns a non-nil *RestError if an error occurs or the response is not in the 2xx family.

func (*Client) Get

func (c *Client) Get(endpoint string, resp interface{}) error

Get issues a GET request to the specified endpoint and parses the response into resp. It will return an error if it failed to send the request, a *RestError if the response wasn't a 2xx status code, or an error from package json's Decode.

func (*Client) NewFormRequest

func (c *Client) NewFormRequest(method Method, endpoint string, params map[string]string) *Request

NewFormRequest generates a new Request object with a form encoded body based on the params map.

func (*Client) NewJsonRequest

func (c *Client) NewJsonRequest(method Method, endpoint string, obj interface{}) (req *Request)

NewJsonRequest generates a new Request object and JSON encodes the provided obj. The JSON object will be set as the body and included in the request.

func (*Client) NewRequest

func (c *Client) NewRequest(method Method, endpoint string, ctype string, body io.Reader) (req *Request)

NewRequest generates a new Request object that will send bytes read from body to the endpoint.

func (*Client) Post

func (c *Client) Post(endpoint string, req interface{}, resp interface{}) error

Post issues a POST request to the specified endpoint with the req payload marshaled to JSON and parses the response into resp. It will return an error if it failed to send the request, a *RestError if the response wasn't a 2xx status code, or an error from package json's Decode.

func (*Client) Put

func (c *Client) Put(endpoint string, req interface{}, resp interface{}) error

Put issues a PUT request to the specified endpoint with the req payload marshaled to JSON and parses the response into resp. It will return an error if it failed to send the request, a *RestError if the response wasn't a 2xx status code, or an error from package json's Decode.

func (*Client) Result

func (c *Client) Result(req *Request, resp interface{}) error

Result performs the request described by req and unmarshals a successful HTTP response into resp. If resp is nil, the response is discarded.

func (*Client) SetAccessToken

func (c *Client) SetAccessToken(token string)

Set the access Token

func (*Client) SetTimeout

func (c *Client) SetTimeout(duration time.Duration)

SetTimeout sets the timeout of a client to the given duration.

type Method

type Method string

Method wraps HTTP verbs for stronger typing.

type Request

type Request struct {
	Method  Method
	URL     *url.URL
	Headers http.Header
	// contains filtered or unexported fields
}

Request encapsulates functionality making it easier to build REST requests.

func (*Request) HTTPRequest

func (r *Request) HTTPRequest() (*http.Request, error)

HTTPRequest returns an *http.Request populated with data from r. It may be executed by any http.Client.

type RestError

type RestError struct {
	// The Request that triggered the error.
	Req *http.Request
	// The Resposne that the request returned.
	Resp *http.Response

	// ErrBody is the body of the request that errored.
	// Not named Body since there is an accessor method.
	ErrBody *string
	// contains filtered or unexported fields
}

RestError is returned from REST transmissions to allow for inspection of failed request and response contents.

func (*RestError) Body

func (r *RestError) Body() string

func (*RestError) Error

func (r *RestError) Error() string