README
¶
YARC
Yet another rest client (for golang)
Yarc is a Go HTTP client library for creating and sending API requests. Check usage or the examples to learn how to yarc into your API client.
Features
- IMO Nice API
- Base/Request: Extend Yarc for different endpoints
- External cache support
- Native JSON support for sending/receiveng structs
- Access to http.Request && http.Response
- Collection of helpers for nice defaults
- Mock server for integration tests: Yams
StupidSimple cache implementation: Yasci
Install
go get github.com/tinchogob/yarc
Documentation
Read GoDoc
Usage
Yarc uses dave's cheney funcional options pattern There a number of functional option functions to customize each client/request.
The can be applied to Yarc's constructor or to Yarc's request executor.
For example, create a base Yarc client with a host and then extend this client to do a request for method+path.
client, err := Yarc.New(Host("https://api.mercadolibre.com))
if err != nil {
panic(err)
}
r, err := client.Go(
GET(),
Path("/items/1234567"),
)
Query, Headers and on
r, err := client.Go(
GET(),
Header("Connection", "keep-alive"),
Path("/items/1234567"),
Query("attributes","id,permalink"),
)
Body
While dealing with JSON requests/response APIS, Yarcs provides some nice helpers out of the box.
Posting JSON
Define JSON tagged structs. Use JSON to JSON encode a struct as the Body on requests.
type ItemRequest struct {
ID string `json:"id"`
Permalink string `json:"permalink"`
}
item := ItemRequest{
ID: "123",
Permalink: "http://permalink.com",
}
r, err := client.Go(
POST(),
Header("Connection", "keep-alive"),
Path("/items/1234567"),
Query("attributes","id,permalink"),
JSON(item),
)
Requests will include an application/json Content-Type header.
ToJSON
Define JSON structs to decode responses. Use ToJSON(body interface{}, errBody interface{}) to decode the response body into body if 2xx or else to errBody.
type Item struct {
ID string `json:"id"`
Permalink string `json:"permalink"`
}
type ApiError struct {
Message string `json:"message"`
Cause string `json:"cause"`
}
item := Item{}
errB := ApiError{}
r, err := client.Go(
GET(),
Header("Connection", "keep-alive"),
Path("/items/1234567"),
Query("attributes","id,permalink"),
ToJSON(&item, &errB),
)
fmt.Println(item, errB)
Accesing to http.Request
Yarcs provides an extension point called With to change/enhance each request
r, err := client.Go(
GET(),
Path("/items/1234567"),
With(func(opts Yarc.Options, req *http.Request) *http.Request {
return req.WithContext(context.Background())
})
)
License
Documentation
¶
Index ¶
- func BaseClient(maxIdleConnsPerHost int, connectionTO time.Duration, requestTO time.Duration) *http.Client
- func BaseTrace() func(Options) (*httptrace.ClientTrace, error)
- func Body(body []byte) optionFunc
- func Client(client *http.Client) optionFunc
- func GET() optionFunc
- func Header(key string, value string) optionFunc
- func Histrix(timeout int, maxConcurrentRequests int, errorPercentThreshold int, ...) optionFunc
- func Host(host string) optionFunc
- func JSON(entity interface{}) optionFunc
- func POST() optionFunc
- func Params(params ...string) optionFunc
- func Path(path string) optionFunc
- func Query(key string, value string) optionFunc
- func ToJSON(body interface{}, errBody interface{}) optionFunc
- func Trace(trace func(Options) (*httptrace.ClientTrace, error)) optionFunc
- func With(with WithFunc) optionFunc
- func WithCache(c Cache) optionFunc
- type Cache
- type Options
- type WithFunc
- type Yarc
- type Yikes
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BaseClient ¶
func Body ¶
func Body(body []byte) optionFunc
Body sets the request body to the provided []byte There a number of helper functions that simplifies usual cases such as marhsalling a json as the request body see JSON(), XML()
func Client ¶
Client lets you use a custom http.Client. By default yarc will use the default http.Client.
func Header ¶
Header adds name: value to the request headers You should call Header as many times as headers you want to set. Header will preserve previously setted headers.
func JSON ¶
func JSON(entity interface{}) optionFunc
JSON sets the request body to the JSON marshall of the provided entity. It also adds "Content-Type: application/json" request header
func Params ¶
func Params(params ...string) optionFunc
Params sets the replace values for every %s in the request Path. Its intended to be used in conjunction with Path. For example: yarc.Go(Host("/ping/%s"),Params("me")) so yarc ends up calling "/ping/me".
func Path ¶
func Path(path string) optionFunc
Path sets the base path for this request. You should use a generic path with a format string (with %s) so that its generic and can identify all similar requests. Its intended to be used in conjunction with Params. For example: yarc.Go(Host("/ping/%s"),Params("me")) so yarc ends up calling "/ping/me".
func Query ¶
Query adds key=value queryparam to the request. You should call Query as many time as params you have. They will be concatenated in the same order Query was called. TODO should be safe and sanitize this input
func ToJSON ¶
func ToJSON(body interface{}, errBody interface{}) optionFunc
ToJSON reads the response body and if OK tries to json.Uunmarshall it to body. If not OK tries to json.Uunmarshall it to errBody. It also adds "Accept: application/json" to the request headers.
Types ¶
type Cache ¶
type Cache interface {
Get(key *http.Request) (*http.Response, error)
Set(key *http.Request, response *http.Response) error
}
Cache is Yarc's cache interface. Implementations must be goroutine safe. cache methods will be called for every request, so implementations should define when they want a hit and when they should set. There is an example implementation called yaci
type Options ¶
type Options struct {
Method string
Host string
Path string
Params []string
Query []string
ReqBody []byte
Headers http.Header
Client *http.Client
// contains filtered or unexported fields
}
Yarc options. You shouldn't use this directly but with option functions. Option functions will be applied in order. Each request may set its own option functions that will be applied after builder options and may override or add options.
type WithFunc ¶
Provides complete access to the request. You can modify or even return a new request.
type Yarc ¶
type Yarc struct {
// contains filtered or unexported fields
}
Yarc is an HTTP request builder and sender
Example ¶
ms, err := yams.New(8181)
if err != nil {
panic(err)
}
ms.Add(
yams.Mock{
Method: http.MethodPost,
URL: "/items/1/ping/2?attributes=id",
ReqBody: []byte("{\"id\":\"ping\"}"),
RespStatus: http.StatusOK,
RespBody: []byte("{\"id\":\"pong\"}"),
Wait: time.Millisecond * 100,
Times: 2,
},
)
yarc, err := New(
Client(BaseClient(1, time.Second, time.Second)),
Host("http://127.0.0.1:8181"),
Path("/items/%s/ping/%s"),
Header("Connection", "keep-alive"),
Header("Cache-Control", "no-cache"),
Trace(BaseTrace()),
With(Debug(os.Stdout)),
WithCache(yasci.New(time.Millisecond*100, 100)),
)
if err != nil {
panic(err)
}
wg := new(sync.WaitGroup)
for i := 0; i < 1; i++ {
time.Sleep(time.Millisecond * 200)
wg.Add(1)
go func() {
//request body
body := &struct {
ID string `json:"id"`
}{"ping"}
//response struct to unmarshall response OK
resp := &struct {
ID string `json:"id"`
}{}
//response struct to unmarshall response NOK
errBody := &struct {
ID string `json:"id"`
}{}
res, err := yarc.Go(
POST(),
Header("X-Name", "Martin"),
JSON(body),
Params("1", "2"),
Query("attributes", "id"),
With(Context(context.Background())),
ToJSON(resp, errBody),
)
wg.Done()
if err != nil {
fmt.Println(err.Error())
if res != nil {
fmt.Printf("%d - %s\n", res.StatusCode, errBody.ID)
}
return
}
fmt.Printf("%d - %s\n", res.StatusCode, resp.ID)
}()
}
wg.Wait()
ms.Close()
Output:
Source Files
Directories