sawyer

README

Sawyer

Status: Very experimental

Sawyer is an HTTP user agent for REST APIs. It is a spiritual compliment to the Ruby sawyer gem.

Use this to build clients for HTTP/JSON APIs that behave like the GitHub API.

Usage

type User struct {
  Login string `json:"login"`
}

class ApiError struct {
  Message strign `json:"message"`
}

client := sawyer.NewFromString("https://api.github.com")

// the GitHub API prefers a vendor media type
client.Headers.Set("Accept", "application/vnd.github+json")

apierr := &ApiError{} // decoded from response body on non-20x responses
user := &User{}
req := client.NewRequest("user/21", apierr)
res := req.Get(user)

// get the user's repositories
apierr := &ApiError{}
repos := new([]Repository)
req := client.NewRequest(res.Hyperlink("repos", sawyer.M{"page": "2"}), apierr)
res := req.Get(repos)

// post a new user
mtype := mediatype.Parse("application/vnd.github+json")
apierr := &ApiError{}
userInput := &User{Login: "bob"}
userOutput := &User{}
req := client.NewRequest("users", apierr)
err := req.SetBody(mtype, userInput)
res := req.Post(userOutput)

Documentation

Index

• Constants
• func UseApiError(status int) bool
• type Client
  • func New(endpoint *url.URL, client *http.Client) *Client
  • func NewFromString(endpoint string, client *http.Client) (*Client, error)
  • func (c *Client) NewRequest(rawurl string) (*Request, error)
  • func (c *Client) ResolveReference(u *url.URL) *url.URL
  • func (c *Client) ResolveReferenceString(rawurl string) (string, error)
• type Request
  • func (r *Request) Delete() *Response
  • func (r *Request) Do(method string) *Response
  • func (r *Request) Get() *Response
  • func (r *Request) Head() *Response
  • func (r *Request) Options() *Response
  • func (r *Request) Patch() *Response
  • func (r *Request) Post() *Response
  • func (r *Request) Put() *Response
  • func (r *Request) SetBody(mtype *mediatype.MediaType, input interface{}) error
• type Response
  • func ResponseError(err error) *Response
  • func (r *Response) AnyError() bool
  • func (r *Response) Decode(resource interface{}) error
  • func (r *Response) Error() string
  • func (r *Response) IsApiError() bool
  • func (r *Response) IsError() bool

Constants

const (
	HeadMethod    = "HEAD"
	GetMethod     = "GET"
	PostMethod    = "POST"
	PutMethod     = "PUT"
	PatchMethod   = "PATCH"
	DeleteMethod  = "DELETE"
	OptionsMethod = "OPTIONS"
)

Functions

func UseApiError

func UseApiError(status int) bool

Types

type Client

type Client struct {
	HttpClient *http.Client
	Endpoint   *url.URL
	Header     http.Header
	Query      url.Values
}

A Client wraps an *http.Client with a base url Endpoint and common header and query values.

func New

func New(endpoint *url.URL, client *http.Client) *Client

New returns a new Client with a given a URL and an optional client.

func NewFromString

func NewFromString(endpoint string, client *http.Client) (*Client, error)

NewFromString returns a new Client given a string URL and an optional client.

func (*Client) NewRequest

func (c *Client) NewRequest(rawurl string) (*Request, error)

func (*Client) ResolveReference

func (c *Client) ResolveReference(u *url.URL) *url.URL

ResolveReference resolves a URI reference to an absolute URI from an absolute base URI. It also merges the query values.

func (*Client) ResolveReferenceString

func (c *Client) ResolveReferenceString(rawurl string) (string, error)

ResolveReference resolves a string URI reference to an absolute URI from an absolute base URI. It also merges the query values.

type Request

type Request struct {
	Client    *http.Client
	MediaType *mediatype.MediaType
	Query     url.Values
	*http.Request
}

func (*Request) Delete

func (r *Request) Delete() *Response

func (*Request) Do

func (r *Request) Do(method string) *Response

func (*Request) Get

func (r *Request) Get() *Response

func (*Request) Head

func (r *Request) Head() *Response

func (*Request) Options

func (r *Request) Options() *Response

func (*Request) Patch

func (r *Request) Patch() *Response

func (*Request) Post

func (r *Request) Post() *Response

func (*Request) Put

func (r *Request) Put() *Response

func (*Request) SetBody

func (r *Request) SetBody(mtype *mediatype.MediaType, input interface{}) error

type Response

type Response struct {
	ResponseError error
	MediaType     *mediatype.MediaType
	MediaHeader   *mediaheader.MediaHeader

	BodyClosed bool
	*http.Response
	// contains filtered or unexported fields
}

func ResponseError

func ResponseError(err error) *Response

func (*Response) AnyError

func (r *Response) AnyError() bool

func (*Response) Decode

func (r *Response) Decode(resource interface{}) error

func (*Response) Error

func (r *Response) Error() string

func (*Response) IsApiError

func (r *Response) IsApiError() bool

func (*Response) IsError

func (r *Response) IsError() bool