README
¶
An HTTP networking client written in go.
GoHTTP is built on top of the net/http package and is designed to make integrating with JSON APIs from golang applications simple and easy.
Why another HTTP Client?
GoHTTP offer two distinct, out-of-the-box features that separate it from other networking clients.
- Rate Limiting - Most public APIs are going to have some form of rate limiting requirements. GoHTTP leverages Funnel to make conforming to these rate limits trivial.
- Retry w/ Exponential BackOff - Systems can fail or error in the wild and applications should be resilient.
GoHTTPmakes it easy for applications to specify the HTTP status codes that should result in a retry.GoHTTPretries using an exponential backoff algorithm powered by Exponential Backoff.
GoHTTP also provides syntactic sugar on top of the net/http package that makes networking easier from go applications (i.e. applications can use maps for request and response JSON bodies).
Features
- HTTP verbs supported Get, Put, Post, Patch, Delete
- Rich object models for requests and responses
- JSON and Form Data requests
- Header and method constants
- Retry with exponential backoff
- Rate limiting backed by Redis
- Response JSON parsing
- JSON pretty printing
- Full documentation
- Comprehensive Unit Test Coverage
Install
$ go get github.com/meshhq/gohttp
Import
import "github.com/meshhq/gohttp"
Examples
GET request
request := gohttp.Request{Method: gohttp.GET}
client := &gohttp.NewClient("api.google.com", nil)
response, err := client.Execute(request)
POST request
request := &gohttp.Request{
Method: gohttp.POST,
URL: "/users",
Body: map[string]interface{}{"first_name": "Kevin"},
}
client := gohttp.NewClient("api.google.com", nil)
response, err := client.Execute(request)
Documentation
Client
All requests are executed with a Client. Client objects can hold global parameters such as a baseURL or a set of headers. Global parameters will be applied to each request that is executed by the Client.
baseURL := "api.google.com"
headers := map[string]string{gohttp.Accept : "application/json"}
client := gohttp.NewClient(baseURL, headers)
Request
gohttp provides a Request object which makes building HTTP request simple and readable. The URL parameter of a request is relative to the baseURL parameter of a the Client that executes it.
request := &gohttp.Request{
Method: gohttp.POST,
URL: "/users",
Body: map[string]interface{}{"first_name": "Kevin"},
}
response, err := client.Execute(request)
Request Execution
A call to the Execute method on a Client object will return a Response object and an error that describes any failure that occurred.
response, err := client.Execute(request)
if err != nil {
return err
}
fmt.Printf("Response: %v", response)
Response
The Response object contains parsed information about the outcome of an HTTP request.
fmt.Printf("Code: %v\n", response.Code) // int containing the response code.
fmt.Printf("Body: %v\n", response.Body) // interface{} containing the parsed response body.
fmt.Printf("Request: %v\n", response.Request) // `gohttp.Request` object which is a pointer to the original request.
Pretty Printing
Applications can also pretty print response objects via the GoHTTP convenience method PrettyPrint. This method is very useful when debugging http requests.
gohttp.PrettyPrint(response)
Example PrettyPrint output.
{
"Code": 201,
"Data": "",
"Body": null,
"Error": null,
"Request": {
"Method": "POST",
"Header": {},
"URL": "/test",
"Params": null,
"Body": {
"name": "test"
},
"Form": null
}
}
Retry
GoHTTP implements sophisticated retry logic with exponential backoff. Applications can configure the status codes for which an application should retry a request via the RetryableStatusCodes parameter on a Client object.
client.RetryableStatusCodes = []int{403} // Rate Limit Exceeded
Underneath the hood, GoHTTP leverages the Exponential Backoff package for building and executing the backoff algorithm. GoHTTP supplies a default backoff algorithm implementation, but applications can supply their own via the Backoff parameter on a Client object.
var backOff := func() error {
// Algorithm configuration
}
client.Backoff = backOff
Rate Limiting
GoHTTP provides robust, out of the box rate limiting support. This makes it very easy to conform with rate limiting policies published by APIs. Underneath the hood, GoHTTP leverages Funnel, a distributed rate limiter backed by redis.
Limit Info
Applications can configure their rate limiting policy by supplying a LimitInfo object to a Client object.
token- A unique token upon which requests are limited. For example, if all requests to the gmail API need to be limited, applications could use the token "gmail".MaxRequests- The maximum number of requests that can take place within a given time interval.TimeInterval- The time interval in (milliseconds) to which theMaxRequestsparameter applies.
info := &RateLimitInfo{
Token: "unique-token",
MaxRequests: 10,
TimeInterval: 1000,
}
client.SetRateLimiterInfo(info)
Applications can concurrently execute requests to the same client from as many goroutines as they wish. The Client will handle queuing requests with redis, and ensure that the rate limit is not breached and all requests are executed.
Contributing
PRs are welcome, but will be rejected unless test coverage is updated
Documentation
¶
Index ¶
- Constants
- func Backoff() *backoff.ExponentialBackOff
- func FormData(data interface{}) (io.Reader, error)
- func JSONData(values interface{}) (io.Reader, error)
- func ParseJSON(data io.Reader) (interface{}, error)
- func PrettyPrint(item interface{})
- type BasicAuth
- type Client
- func (c *Client) Delete(request *Request) (*Response, error)
- func (c *Client) Execute(req *Request) (*Response, error)
- func (c *Client) Get(request *Request) (*Response, error)
- func (c *Client) Patch(request *Request) (*Response, error)
- func (c *Client) Post(request *Request) (*Response, error)
- func (c *Client) Put(request *Request) (*Response, error)
- func (c *Client) SetBasicAuth(username string, password string)
- func (c *Client) SetRateLimiterInfo(limitInfo *funnel.RateLimitInfo) error
- type Param
- type Request
- type Response
Constants ¶
const ( DefaultInitialInterval = 100 * time.Millisecond DefaultRandomizationFactor = 0.75 DefaultMultiplier = 2 DefaultMaxInterval = 3 * time.Second DefaultMaxElapsedTime = 5 * time.Second )
GoHTTP Default backoff parameters.
const ( GET = "GET" POST = "POST" PUT = "PUT" PATCH = "PATCH" DELETE = "DELETE" )
HTTP Methods
const ( ContentType = "Content-Type" ContentLength = "Content-Length" Accept = "Accept" Authorization = "Authorization" UserAgent = "User-Agent" )
HTTP Header Constants
Variables ¶
This section is empty.
Functions ¶
func Backoff ¶
func Backoff() *backoff.ExponentialBackOff
Backoff returns a backoff.ExponentialBackOff algorithm with the default GoHTTP backoff policy.
func ParseJSON ¶
ParseJSON parses the JSON data from an `io.Reader` into an `interface{}`. This method utilizes the `UserNumber` feature of the `json.Decoder` which causes the Decoder to unmarshal a number into an interface{} as a Number instead of as a float64.
func PrettyPrint ¶
func PrettyPrint(item interface{})
PrettyPrint prints a JSON representation in a pretty printed manner.
Types ¶
type BasicAuth ¶
type BasicAuth struct {
// Username for basic authentication.
Username string
// Password for basic authentication.
Password string
}
BasicAuth models a set of basic authentication credentials.
type Client ¶
type Client struct {
// BaseURL is base URL used for all requests executed by the client.
BaseURL string
// Headers model the global headers to be used for all requests issued by the client.
Headers http.Header
// BasicAuth
BasicAuth *BasicAuth
// RetryableStatusCodes is an array of codes that are retryable.
RetryableStatusCodes []int
// Backoff ...
Backoff *backoff.ExponentialBackOff
// contains filtered or unexported fields
}
Client models an HTTP client.
A GoHTTP Client can contain global request parameters, such as a BaseURL, a set of Headers, or Basic Authentication Credentials. All global parameters will be applied to each request executed by the client.
The GoHTTP client also has built in support support for retry (with exponential backoff and rate limiting).
func (*Client) Execute ¶
Execute executes the HTTPc request described with the given `gohttp.Request`.
func (*Client) Patch ¶
Patch performs an HTTP PATCH request with the supplied URL string and parameters.
func (*Client) SetBasicAuth ¶
SetBasicAuth configures basic authentication credentials for the client.
func (*Client) SetRateLimiterInfo ¶
func (c *Client) SetRateLimiterInfo(limitInfo *funnel.RateLimitInfo) error
SetRateLimiterInfo provides..
type Request ¶
type Request struct {
// Method is the HTTP method to be used for the request.
Method string
// Header are the headers for the request.
Header http.Header
// URL is the route to be used for the request. The URL should be relative to the BaseURL of the client.
URL string
// Params contains the URL parameters to be used with the request.
Params []Param
// Body contains the JSON body to be used for the request. Body will be sent as application/json.
Body interface{}
// Form contains the form to be used for the request. Form will be sent as application/x-www-form-urlencoded.
Form interface{}
}
Request models an HTTP request.
GoHTTP Request objects are sumbitted to a `gohttp.Client` for execution.
type Response ¶
type Response struct {
// Code is the response code for the request.
Code int
// Data contains the raw response data from an request.
Data []byte
// Body is the deserialized response body returned from an request.
Body interface{}
// Error is an error that may have occurred during the request.
Error error
// Request is the gohttp.Request object used to generate the response.
Request *Request
}
Response models a response from HTTP request.
The GoHTTP Response object provides a convenient model for handling the result of an HTTP request.
func NewResponse ¶
NewResponse builds a `gohttp.Response` object from an `http.Response` object.
Source Files