README
¶
github.com/tetratom/rq
rq is a no-nonsense library for working with rest apis
highlights
- request constructors pass values: one
rq.Requestcan be used as the basis of another without copy concerns - easy access to common operations:
Path(),Queryf(),SetHeader(),Is2xx(), and many more - support for arbitrary request, response middleware, and marshallers
- context-first
example
import "github.com/tetratom/rq"
req := rq.
Begin("https://httpbin.org").
Path("get").
Queryf("x", "y%d", 1)
rep, err := req.GET(context.Background())
switch {
case err != nil:
panic(err)
case !rep.Is2xx():
panic("bad response!")
}
log.Printf("response: %s", rep.ReadStringOrPanic())
Documentation
¶
Overview ¶
rq is a wrapper for go's http client.
Example (SigningMiddleware) ¶
package main
import (
"context"
"crypto/md5"
"encoding/hex"
"errors"
"fmt"
"github.com/tetratom/rq"
"io"
"io/ioutil"
)
// NewRequestSigningMiddleware returns a rq request middleware that generates
// an example digest based on a secret value and the request body (if any).
// The result is the X-Request-Signature header, a hex-encoded MD5 hash.
//
// If the request has a body, it will be fully buffered into memory.
func NewRequestSigningMiddleware(secret string) rq.RequestMiddleware {
return func(req rq.Request) rq.Request {
digest := md5.New()
io.WriteString(digest, secret)
if req.Body != nil {
data, _ := ioutil.ReadAll(req.Body.Reader())
digest.Write(data)
req = req.SetBodyBytes(data)
}
return req.
SetHeader(
"X-Request-Signature",
hex.EncodeToString(digest.Sum(nil)))
}
}
// NewResponseVerifyingMiddleware returns a rq response middleware that converts
// a successful response into a failure if the response did not include the
// X-Response-Signature header.
func NewResponseVerifyingMiddleware() rq.ResponseMiddleware {
return func(req rq.Request, rep rq.Response, err error) (rq.Response, error) {
if err != nil {
return rep, err
}
if !rep.HasHeader("X-Response-Signature") {
return rep, errors.New("no response signature")
}
return rep, nil
}
}
func main() {
api := rq.
Begin("http://httpbin.org").
Path("anything").
AddRequestMiddlewares(NewRequestSigningMiddleware("much secure"))
var response HTTPBinResponse
rep, _ := api.SetBodyString("very covert").GET(context.TODO())
rep.UnmarshalJSON(&response)
fmt.Println("first request")
fmt.Println("signature:", response.Headers["X-Request-Signature"])
fmt.Println("body:", response.Data)
_, err := api.
AddResponseMiddlewares(NewResponseVerifyingMiddleware()).
GET(context.TODO())
fmt.Println("second request")
fmt.Println("error:", err) // error: no response signature
}
Output: first request signature: 121aa41cde97e6d27d468e743a8c05a6 body: very covert second request error: no response signature
Index ¶
- func UnmarshalJSON(response Response, value interface{}) error
- func UnmarshalXML(response Response, value interface{}) error
- type Header
- type Marshaller
- type Request
- func (req Request) AddHeader(name string, value string, args ...interface{}) Request
- func (req Request) AddQueryf(name string, value string, args ...interface{}) Request
- func (req Request) AddRequestMiddlewares(middlewares ...RequestMiddleware) Request
- func (req Request) AddResponseMiddlewares(middlewares ...ResponseMiddleware) Request
- func (req Request) DELETE(ctx context.Context) (Response, error)
- func (req Request) Do(ctx context.Context) (Response, error)
- func (req Request) GET(ctx context.Context) (Response, error)
- func (req Request) GetContext() context.Context
- func (req Request) GetError() error
- func (req Request) GetFragment() string
- func (req Request) GetHeader(name string) string
- func (req Request) GetQuery(name string) string
- func (req Request) HasError() bool
- func (req Request) HasHeader(name string) bool
- func (req Request) HeaderMap() http.Header
- func (req Request) Map(mapper func(Request) Request) Request
- func (req Request) MapHeaders(f func([]Header) []Header) Request
- func (req Request) MapURL(f func(url url.URL) url.URL) Request
- func (req Request) Marshal(value interface{}) Request
- func (req Request) MarshalForm(value url.Values) Request
- func (req Request) MarshalJSON(value interface{}) Request
- func (req Request) MarshalXML(value interface{}) Request
- func (req Request) PATCH(ctx context.Context) (Response, error)
- func (req Request) POST(ctx context.Context) (Response, error)
- func (req Request) PUT(ctx context.Context) (Response, error)
- func (req Request) Path(segments ...string) Request
- func (req Request) Pathf(segment string, args ...interface{}) Request
- func (req Request) Prepare(ctx context.Context) (*http.Request, error)
- func (req Request) RemoveHeader(name string) Request
- func (req Request) RemoveQuery(name string) Request
- func (req Request) ReplaceQuery(query url.Values) Request
- func (req Request) SetApiKey(key string) Request
- func (req Request) SetBasicAuth(username, password string) Request
- func (req Request) SetBearerToken(token string) Request
- func (req Request) SetBody(body RequestBody) Request
- func (req Request) SetBodyBytes(data []byte) Request
- func (req Request) SetBodyReader(r io.Reader) Request
- func (req Request) SetBodyString(data string) Request
- func (req Request) SetClient(client *http.Client) Request
- func (req Request) SetError(err error) Request
- func (req Request) SetFragment(fragment string) Request
- func (req Request) SetHeader(name string, value string, args ...interface{}) Request
- func (req Request) SetMarshaller(marshaller Marshaller) Request
- func (req Request) SetMethod(method string) Request
- func (req Request) SetQueryf(name string, value string, args ...interface{}) Request
- func (req Request) SetRequestMiddlewares(middlewares ...RequestMiddleware) Request
- func (req Request) SetResponseMiddlewares(middlewares ...ResponseMiddleware) Request
- func (req Request) SetURL(value string) Request
- func (req Request) SetUnmarshaller(unmarshaller Unmarshaller) Request
- func (req Request) SetUserAgent(ua string) Request
- type RequestBody
- type RequestBodyBytes
- type RequestBodyReader
- type RequestBodyString
- type RequestMiddleware
- type Response
- func (resp Response) Close() error
- func (resp *Response) GetHeader(name string) string
- func (resp *Response) HasHeader(name string) bool
- func (resp Response) IgnoringContentType() Response
- func (resp Response) Is1xx() bool
- func (resp Response) Is2xx() bool
- func (resp Response) Is3xx() bool
- func (resp Response) Is4xx() bool
- func (resp Response) Is5xx() bool
- func (resp *Response) LookupHeader(name string) (string, bool)
- func (resp Response) Map(f func(Response) Response) Response
- func (resp Response) ReadAll() ([]byte, error)
- func (resp Response) ReadString() (string, error)
- func (resp Response) ReadStringOrPanic() string
- func (resp Response) Status() int
- func (resp Response) StatusOneOf(statuses ...int) bool
- func (resp Response) Unmarshal(v interface{}) error
- func (resp Response) UnmarshalJSON(v interface{}) error
- func (resp Response) UnmarshalXML(v interface{}) error
- type ResponseMiddleware
- type Unmarshaller
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func UnmarshalJSON ¶
func UnmarshalXML ¶
Types ¶
type Marshaller ¶
Marshaller is a function for marshalling the given value into the given request. The marshaller is expected to set any additional relevant properties, such as the Content-Type header.
If marshalling fails, the error of the resultant request should be set using SetError().
type Request ¶
type Request struct {
URL url.URL
Method string
Headers []Header
Client *http.Client
Body RequestBody
RequestMiddlewares []RequestMiddleware
ResponseMiddlewares []ResponseMiddleware
Marshaller Marshaller
Unmarshaller Unmarshaller
// contains filtered or unexported fields
}
func FormMarshaller ¶
func JSONMarshaller ¶
func NOOPMarshaller ¶
func XMLMarshaller ¶
func (Request) AddRequestMiddlewares ¶
func (req Request) AddRequestMiddlewares(middlewares ...RequestMiddleware) Request
func (Request) AddResponseMiddlewares ¶
func (req Request) AddResponseMiddlewares(middlewares ...ResponseMiddleware) Request
func (Request) GetContext ¶
GetContext returns the context currently associated with the request. The context is set as part of an execution method, so this is only useful in middlewares.
func (Request) GetFragment ¶
func (Request) HeaderMap ¶
HeaderMap returns a copy of the headers assigned to this request.
Modifying the map will affect the request.
func (Request) Marshal ¶
Marshal sets the body of the request by marshalling the given value using the Marshaller set on the request object. If none is set, it is marshalled using the MarshalJSON() method of the request.
func (Request) MarshalJSON ¶
MarshalJSON marshals the given value using the default JSON marshaller. The Content-Type of the request will be set to "application/json; charset=utf-8".
func (Request) MarshalXML ¶
MarshalXML marshals the given value using the default XML marshaller. The Content-Type of the request will be set to "text/xml; charset=utf-8".
func (Request) Prepare ¶
Prepare builds the native http.Request that will be used for the HTTP request. It returns a new instance of request
func (Request) RemoveHeader ¶
func (Request) RemoveQuery ¶
func (Request) SetBasicAuth ¶
func (Request) SetBearerToken ¶
func (Request) SetBody ¶
func (req Request) SetBody(body RequestBody) Request
func (Request) SetBodyBytes ¶
func (Request) SetBodyString ¶
func (Request) SetError ¶
SetError is used to taint a Request. Builder methods can continue to change the request, but executing the request will fail with the given error immediately.
The request can be un-tainted with SetError(nil).
func (Request) SetFragment ¶
func (Request) SetMarshaller ¶
func (req Request) SetMarshaller(marshaller Marshaller) Request
func (Request) SetRequestMiddlewares ¶
func (req Request) SetRequestMiddlewares(middlewares ...RequestMiddleware) Request
func (Request) SetResponseMiddlewares ¶
func (req Request) SetResponseMiddlewares(middlewares ...ResponseMiddleware) Request
func (Request) SetUnmarshaller ¶
func (req Request) SetUnmarshaller(unmarshaller Unmarshaller) Request
func (Request) SetUserAgent ¶
type RequestBody ¶
RequestBody produces readers for requests. Any time a request is executed, the body is set to be the reader returned by Reader(). If a RequestBody is to be reused, the implementation must ensure that every call to Reader() returns a new io.Reader that starts from the beginning.
type RequestBodyBytes ¶
type RequestBodyBytes struct {
Data []byte
}
RequestBodyBytes is a reusable request body of bytes.
func (*RequestBodyBytes) Reader ¶
func (rbb *RequestBodyBytes) Reader() io.Reader
type RequestBodyReader ¶
func (*RequestBodyReader) Reader ¶
func (rbb *RequestBodyReader) Reader() io.Reader
type RequestBodyString ¶
type RequestBodyString struct {
Data string
}
func (*RequestBodyString) Reader ¶
func (rbb *RequestBodyString) Reader() io.Reader
type RequestMiddleware ¶
type Response ¶
type Response struct {
Underlying *http.Response
Unmarshaller Unmarshaller
IgnoreContentType bool
}
func (Response) IgnoringContentType ¶
func (Response) ReadString ¶
func (Response) ReadStringOrPanic ¶
func (Response) StatusOneOf ¶
func (Response) UnmarshalJSON ¶
func (Response) UnmarshalXML ¶
type ResponseMiddleware ¶
ResponseMiddleware intercepts a response. It is also called in case of a request failure, in which case `rep` may be empty, and `err` non-nil. The middleware is expected to return (rep, err) immediately if it is not designed to handle an erroneous response.
The `req` passed to the middleware is exactly the same as was used for the original request. Use req.GetContext() to obtain the request context.
type Unmarshaller ¶
Source Files
Click to show internal directories.
Click to hide internal directories.