README
¶
Rester
Easy http for the REST of us
Goals
- Build a library that makes writing REST clients much less tedious.
- Lots of sugar on common crap for rest calls.
- Tripperware to catch common functionality and be more helpful (like returning an error for 400/500 class errors).
- Dynamic updates to e.g. base URLs if/when configuration changes in realtime.
Example
root := rester.Must(rester.New("apis.example.com"))
root.Transport = rester.All{
rester.MaxStatus(399), // Return an actual error which includes the code and body if the res.Status is 400/500
rester.Logging(logrus.WithField("client", "gitlab")), // Log requests
}.Wrap(http.DefaultTransport)
apiv1 := rester.Must(client.Sub("/api/v1"))
in := input{Foo: "foo", ID: 1234}
var out foo
err := apiv1.R().Post("foo").JSON(in).Do(context.Background()).JSON(&out)
Documentation
¶
Overview ¶
Example ¶
package main
import (
"context"
"fmt"
"log"
"net/http"
"github.com/sirupsen/logrus"
)
var (
root = Must(New("https://gitlab.aexp.com"))
v4 = Must(root.Sub("api/v4"))
issues = Must(v4.Sub("issues"))
projects = Must(v4.Sub("projects"))
)
func init() {
root.Transport = All{
MaxStatus(399),
Logging(logrus.WithField("client", "gitlab")),
}.Wrap(http.DefaultTransport)
}
func main() {
var is []interface{}
ctx := context.Background()
if err := issues.R().Do(ctx).JSON(&is); err != nil {
log.Fatal(err)
}
if err := issues.R().Get("sub").Do(ctx).JSON(&is); err != nil {
log.Fatal(err)
}
if err := issues.R().Get("sub/%d", 3).Do(ctx).JSON(&is); err != nil {
log.Fatal(err)
}
req, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://foobar.aexp.com", nil)
if err != nil {
log.Fatal(err)
}
res, err := projects.do(req)
if err != nil {
log.Fatal(err)
}
res.Body.Close()
fmt.Println(len(is))
}
Output:
Index ¶
- Variables
- func BasicMerge(a, b *url.URL) *url.URL
- func ReqFunc[I, O any](c *Client, path, verb string) func(ctx context.Context, in I) (*O, error)
- type All
- type BadStatusErr
- type Client
- type DefaultHeaders
- type MaxStatus
- type MergeFunc
- type MergeHeaders
- type ReplaceHeaders
- type Request
- func (r *Request) Delete(fmt string, args ...interface{}) *Request
- func (r *Request) Do(ctx context.Context) *Response
- func (r *Request) Get(fmt string, args ...interface{}) *Request
- func (r *Request) JSON(ifc interface{}) *Request
- func (r *Request) Patch(fmt string, args ...interface{}) *Request
- func (r *Request) Post(fmt string, args ...interface{}) *Request
- func (r *Request) Put(fmt string, args ...interface{}) *Request
- func (r *Request) SetHeader(k, v string) *Request
- func (r *Request) SetQuery(k, v string) *Request
- func (r *Request) WithBasicAuth(user, pass string) *Request
- func (r *Request) WithBody(rd io.Reader) *Request
- func (r *Request) WithHeader(h http.Header) *Request
- func (r *Request) WithMethod(m string) *Request
- func (r *Request) WithQuery(v url.Values) *Request
- type RequestFunc
- type Response
- type ResponseFunc
- type Tripperware
- type TripperwareFunc
- type URLMerger
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultMerger is the Merger used unless a client has one specified. DefaultMerger = MergeFunc(BasicMerge) )
var ( // DefaultTransport is the fallback transport mechanism for when a transport // is unspecified. DefaultTransport = http.DefaultTransport )
Any URLMerger can merge a URL
Functions ¶
func BasicMerge ¶
BasicMerge is a MergeFunc that does (believe it or not) a basic URL merge. Path and query are merged, and all else comes from the left (`a`) URL.
Types ¶
type All ¶
type All []Tripperware
All is a slice of Tripperwares that applies all of them in order.
func (All) Wrap ¶
func (a All) Wrap(rt http.RoundTripper) http.RoundTripper
Wrap simply iterates and applies each roundtripper as a wrapper.
type BadStatusErr ¶
func (*BadStatusErr) Error ¶
func (b *BadStatusErr) Error() string
type Client ¶
A Client is the basis for a very basic HTTP RESTful client with helpers.
func (*Client) Flat ¶
Flat flattens out the parent hierarchy and decouples the Client from any parent changes. It will also effectively cache the parent URL hierarchy. Can be done if performance is critical or dynamic updates are not desired, or to deliberately decouple from another service.
type DefaultHeaders ¶
DefaultHeaders simplifies setting headers on an outgoing request if they were not already set.
func (DefaultHeaders) Wrap ¶
func (r DefaultHeaders) Wrap(rt http.RoundTripper) http.RoundTripper
Wrap sets all headers that weren't already set on the outgoing request before performing it
type MaxStatus ¶
type MaxStatus int
func (MaxStatus) Wrap ¶
func (m MaxStatus) Wrap(rt http.RoundTripper) http.RoundTripper
type MergeHeaders ¶
MergeHeaders simplifies replacing all headers on an outgoing request.
func (MergeHeaders) Wrap ¶
func (mh MergeHeaders) Wrap(rt http.RoundTripper) http.RoundTripper
Wrap appends slices together to merge headers
type ReplaceHeaders ¶
ReplaceHeaders simplifies replacing all headers on an outgoing request.
func (ReplaceHeaders) Wrap ¶
func (r ReplaceHeaders) Wrap(rt http.RoundTripper) http.RoundTripper
Wrap replaces all headers on the outgoing request before performing it
type Request ¶
type Request struct {
Body io.Reader
Method string
Header http.Header
Query url.Values
// contains filtered or unexported fields
}
func (*Request) SetQuery ¶
SetQuery will set a key/value pair in the URL query params for the final request. It will override any colliding values in the fmt.
func (*Request) WithBasicAuth ¶
WithBasicAuth sets up basic auth headers on the request.
func (*Request) WithMethod ¶
WithMethod sets the request method to be the given method.
type RequestFunc ¶
A RequestFunc is an implementation of Tripperware that simply modifies a request before it is RoundTripped.
func BasicAuth ¶
func BasicAuth(u, p string) RequestFunc
BasicAuth returns a Tripperware that adds basic auth to a request.
func (RequestFunc) Wrap ¶
func (rf RequestFunc) Wrap(rt http.RoundTripper) http.RoundTripper
Wrap modifies the request prior to RoundTripping it.
type ResponseFunc ¶
A ResponseFunc is an implementation of Tripperware that only modifies a response once it is RoundTripped.
func (ResponseFunc) Wrap ¶
func (rf ResponseFunc) Wrap(rt http.RoundTripper) http.RoundTripper
type Tripperware ¶
type Tripperware interface {
Wrap(rt http.RoundTripper) http.RoundTripper
}
A Tripperware can implement some specific functionality around request/response/errors.
func Logging ¶
func Logging(entry *logrus.Entry) Tripperware
Logging returns a Tripperware that logs client requests.
func Metrics ¶
func Metrics() Tripperware
Metrics returns a Tripperware that instruments prometheus metrics. The following metrics are provided:
http_tripper_started_requests_total - counter http_tripper_completed_requests_total - counter http_tripper_completed_latency_seconds - histogram http_tripper_request_size_bytes - histogram http_tripper_response_size_bytes - histogram
func WithTrace ¶
func WithTrace(tr opentracing.Tracer) Tripperware
WithTrace starts a span for all outgoing requests, and injects that span into the ougoing request http headers, and records tags for both request and response if necessary.
type TripperwareFunc ¶
type TripperwareFunc func(rt http.RoundTripper) http.RoundTripper
A TripperwareFunc is the typical one-liner func implementation of a single-method interface.
func Backoff ¶
func Backoff(b backoff.BackOff) TripperwareFunc
Backoff wraps a cenkalti Backoff policy with a middleware that attempts multiple times to perform a request, returning immediately if the error is a code 4xx.
func (TripperwareFunc) Wrap ¶
func (t TripperwareFunc) Wrap(rt http.RoundTripper) http.RoundTripper
Wrap calls the func to implement Tripperware.
Source Files
Directories