README.md
1go-retryablehttp
2================
3
4[][travis]
5[][godocs]
6
7[travis]: http://travis-ci.org/hashicorp/go-retryablehttp
8[godocs]: http://godoc.org/github.com/hashicorp/go-retryablehttp
9
10The `retryablehttp` package provides a familiar HTTP client interface with
11automatic retries and exponential backoff. It is a thin wrapper over the
12standard `net/http` client library and exposes nearly the same public API. This
13makes `retryablehttp` very easy to drop into existing programs.
14
15`retryablehttp` performs automatic retries under certain conditions. Mainly, if
16an error is returned by the client (connection errors, etc.), or if a 500-range
17response code is received (except 501), then a retry is invoked after a wait
18period. Otherwise, the response is returned and left to the caller to
19interpret.
20
21The main difference from `net/http` is that requests which take a request body
22(POST/PUT et. al) can have the body provided in a number of ways (some more or
23less efficient) that allow "rewinding" the request body if the initial request
24fails so that the full request can be attempted again. See the
25[godoc](http://godoc.org/github.com/hashicorp/go-retryablehttp) for more
26details.
27
28Version 0.6.0 and before are compatible with Go prior to 1.12. From 0.6.1 onward, Go 1.12+ is required.
29From 0.6.7 onward, Go 1.13+ is required.
30
31Example Use
32===========
33
34Using this library should look almost identical to what you would do with
35`net/http`. The most simple example of a GET request is shown below:
36
37```go
38resp, err := retryablehttp.Get("/foo")
39if err != nil {
40 panic(err)
41}
42```
43
44The returned response object is an `*http.Response`, the same thing you would
45usually get from `net/http`. Had the request failed one or more times, the above
46call would block and retry with exponential backoff.
47
48## Getting a stdlib `*http.Client` with retries
49
50It's possible to convert a `*retryablehttp.Client` directly to a `*http.Client`.
51This makes use of retryablehttp broadly applicable with minimal effort. Simply
52configure a `*retryablehttp.Client` as you wish, and then call `StandardClient()`:
53
54```go
55retryClient := retryablehttp.NewClient()
56retryClient.RetryMax = 10
57
58standardClient := retryClient.StandardClient() // *http.Client
59```
60
61For more usage and examples see the
62[godoc](http://godoc.org/github.com/hashicorp/go-retryablehttp).
63
){kind=link}
){kind=link}