README
¶
Got - HTTP API Calls
Package got is a super simple net/http wrapper that does the right thing for most JSON REST APIs specifically adding:
- Retry logic with exponential back-off,
- Reading of body with a MaxSize to avoid running out of memory,
- Timeout after 30 seconds.
g := got.New()
response, err := g.NewRequest("PUT", url, []byte("...")).Send()
if err == nil {
// handle error
}
// Make a GET request
response, err := g.NewRequest("GET", url, nil).Send()
// or short hand
response, err := g.Get(url).Send()
// Send JSON in a request
request := g.NewRequest("PUT", url, []byte(`{"key": "value"}`))
request.Header.Set("Content-Type": "application/json")
// or short hand
request := g.Put(url, nil)
err := request.JSON(map[string]{"key": "value"})
// Disable retries for a request
request := g.NewRequest("POST", url, []byte(`{"key": "value"}`))
request.Retries = 0 // Defaults to 5
// Disable retries for all requests
g.Retries = 0
For more details see: godoc.org/github.com/taskcluster/go-got
Documentation
¶
Overview ¶
Package got is a super simple net/http wrapper that does the right thing for most JSON REST APIs specifically adding:
- Retry logic with exponential back-off,
- Reading of body with a MaxSize to avoid running out of memory,
- Timeout after 30 seconds.
Send a request with retries like this:
g := got.New()
response, err := g.NewRequest("PUT", url, []byte("...")).Send()
if err == nil {
// handle error
}
json.Unmarshal(response.Body, &MyObject)
This package will never support streaming requests. For small requests like JSON it is often best to buffer the entire body before parsing it. As slow parsing using a unbuffered decoder can slowdown the request.
It is also much easier to send requests and handled responses with small JSON payloads if there is no dealing with streaming. Streaming particularly complicates retries. If you need to stream the request body, DO NOT use this package.
Index ¶
- Variables
- func DefaultIsTransient(response BadResponseCodeError) bool
- func DefaultMakeRequest(r *Request) (*http.Request, error)
- type BackOff
- type BadResponseCodeError
- type Got
- func (g *Got) Delete(url string) *Request
- func (g *Got) Get(url string) *Request
- func (g *Got) Head(url string) *Request
- func (g *Got) NewRequest(method string, url string, body []byte) *Request
- func (g *Got) Patch(url string, body []byte) *Request
- func (g *Got) Post(url string, body []byte) *Request
- func (g *Got) Put(url string, body []byte) *Request
- type Logger
- type Request
- type Response
Constants ¶
This section is empty.
Variables ¶
var DefaultBackOff = &BackOff{ DelayFactor: 100 * time.Millisecond, RandomizationFactor: 0.25, MaxDelay: 30 * time.Second, }
DefaultBackOff is a simple exponential backoff with delays as follows:
- 400, range: [300; 500]
- 100, range: [75; 125]
- 200, range: [150; 250]
- 800, range: [600; 1000]
var DefaultClient = &http.Client{ Timeout: 30 * time.Second, }
DefaultClient is the default client used by got.New().
Most importantly it has a sane timeout. Which is what you'll want for REST API calls.
var ErrResponseTooLarge = errors.New("Response body is larger than MaxSize")
ErrResponseTooLarge is used to indicate that the response was larger than the safety limit at MaxSize (defined the request)
Functions ¶
func DefaultIsTransient ¶
func DefaultIsTransient(response BadResponseCodeError) bool
DefaultIsTransient determines if an error is transient or persistent.
This is the default implementation of Got.IsTransient, if nothing else is specified. By implementing a custom variant of this method and specifying on Got, it is possible to decide which 5xx error to retry. Default implementation is to retry any 5xx error.
func DefaultMakeRequest ¶
DefaultMakeRequest creates a http.Request from a got.Request.
This is the default implementation of Got.MakeRequest, if nothing else is specified. MakeRequest can be specified, for special use-cases such as generating a new Authorization header for each retry.
Types ¶
type BackOff ¶
type BackOff struct {
DelayFactor time.Duration
RandomizationFactor float64
MaxDelay time.Duration
}
BackOff configuration for retries
type BadResponseCodeError ¶
type BadResponseCodeError struct {
*Response
}
BadResponseCodeError is used to indicate a non-2xx status code
func (BadResponseCodeError) Error ¶
func (e BadResponseCodeError) Error() string
type Got ¶
type Got struct {
Client *http.Client
BackOff *BackOff
Retries int
IsTransient func(BadResponseCodeError) bool
Log Logger
MaxSize int64
MakeRequest func(*Request) (*http.Request, error)
}
Got is a simple HTTP client
func New ¶
func New() *Got
New returns a new Got client with sane defaults for most small REST API requests.
This includes:
- Max 5 retries,
- Exponential back-off: 100, 200, 400, 800 ms with 25% randomization
- Retry any 5xx error,
- ErrResponseTooLarge if response body is larger than 10 MiB,
- Timeout at 30 seconds,
Notice, this different from the defaults you will get with a zero-value Got{} structure.
Note: Depending on the API you are calling you may not wish to use retries, for verbs like POST, PATCH, etc. that aren't idemponent. In that case, you just set Got.Retries = 0, for the instance used for non-idemponent requests.
func (*Got) NewRequest ¶
NewRequest returns a new request with settings from Got
type Logger ¶
type Logger interface {
Println(v ...interface{})
}
Logger is a simple logging interface. This is implicitly implemented by the builtin log package as well as logrus.
Source Files