README
¶
vrest
Simple REST client inspired by the great resty lib.
Why another rest lib?
We really like the API of resty, but there are a few reasons why we created our own lib:
-
No dependencies: vrest has no dependencies.
-
Efficient memory usage: We don't want a rest lib to copy body bytes. The lib user should be in control. vrest gives you access to the body bytes (if available).
-
HTTP abstraction: We want to abstract the HTTP layer away, so there is only one error return value, no HTTP response handling required.
-
Limited scope: This lib only covers default rest APIs with JSON and XML. We don't plan to add support for handling HTML related stuff like form data or multipart file uploads.
-
Improved logging/tracing: Tracing requests was designed with Open Telemetry in mind. There is full access to all request/response data.
-
No data hiding: We provide full access to all internal data in callbacks. You can break things, if you want, so please look at the examples how to perform advanced tasks like overwriting vrest functions.
-
Configurability: Many configurable settings and replaceable functions. Most settings can be set in client (default for all requests) and each request to override client defaults.
-
Easy testing: It is easy to replace functions in vrest. There are also some helper functions to mock responses.
Documentation
¶
Index ¶
- Variables
- func Do(req *Request) error
- func DoHTTPRequest(req *Request) (*http.Response, error)
- func IsJSONContentType(contentType string) bool
- func IsSuccess(req *Request) bool
- func IsXMLContentType(contentType string) bool
- func JSONMarshal(req *Request, v interface{}) ([]byte, error)
- func JSONUnmarshal(req *Request, data []byte, v interface{}) error
- func MustReadFile(t *testing.T, path string) []byte
- func XMLMarshal(req *Request, v interface{}) ([]byte, error)
- func XMLUnmarshal(req *Request, data []byte, v interface{}) error
- type Client
- func (c *Client) NewRequest() *Request
- func (c *Client) NewRequestWithContext(ctx context.Context) *Request
- func (c *Client) SetAuthorization(auth string) *Client
- func (c *Client) SetBaseURL(baseURL string) *Client
- func (c *Client) SetBasicAuth(username, password string) *Client
- func (c *Client) SetBearerAuth(token string) *Client
- func (c *Client) SetContentType(contentType string) *Client
- func (c *Client) SetContentTypeJSON() *Client
- func (c *Client) SetContentTypeXML() *Client
- func (c *Client) SetErrorBodyType(value error) *Client
- func (c *Client) SetLogger(logger *slog.Logger) *Client
- func (c *Client) SetResponseBodyLimit(limit int64) *Client
- func (c *Client) SetTraceBodies(value bool) *Client
- func (c *Client) SetTraceMaker(traceMaker TraceMaker) *Client
- type Doer
- type HTTPDoer
- type MockHTTPResponse
- func MockJSONResponse(statusCode int, body string) *MockHTTPResponse
- func MockJSONResponseFromFile(t *testing.T, statusCode int, filePath string) *MockHTTPResponse
- func MockXMLResponse(statusCode int, body string) *MockHTTPResponse
- func MockXMLResponseFromFile(t *testing.T, statusCode int, filePath string) *MockHTTPResponse
- type Overridables
- type Request
- func (req *Request) ContentType() string
- func (req *Request) Do(method, pathFormat string, values ...any) error
- func (req *Request) DoConnect(pathFormat string, values ...any) error
- func (req *Request) DoDelete(pathFormat string, values ...any) error
- func (req *Request) DoGet(pathFormat string, values ...any) error
- func (req *Request) DoHead(pathFormat string, values ...any) error
- func (req *Request) DoOptions(pathFormat string, values ...any) error
- func (req *Request) DoPatch(pathFormat string, values ...any) error
- func (req *Request) DoPost(pathFormat string, values ...any) error
- func (req *Request) DoPut(pathFormat string, values ...any) error
- func (req *Request) DoTrace(pathFormat string, values ...any) error
- func (req *Request) ForceResponseJSON() *Request
- func (req *Request) ForceResponseXML() *Request
- func (req *Request) SetAuthorization(authValue string) *Request
- func (req *Request) SetBasicAuth(username, password string) *Request
- func (req *Request) SetBearerAuth(token string) *Request
- func (req *Request) SetBody(body interface{}) *Request
- func (req *Request) SetContentLength(contentLength int64) *Request
- func (req *Request) SetContentType(contentType string) *Request
- func (req *Request) SetContentTypeJSON() *Request
- func (req *Request) SetContentTypeXML() *Request
- func (req *Request) SetContext(ctx context.Context) *Request
- func (req *Request) SetHeader(key string, value string) *Request
- func (req *Request) SetHeaderIf(condition bool, key string, value string) *Request
- func (req *Request) SetQueryParam(key string, values ...string) *Request
- func (req *Request) SetQueryParamIf(condition bool, key string, values ...string) *Request
- func (req *Request) SetResponseBody(value interface{}) *Request
- func (req *Request) SetResponseBodyLimit(limit int64) *Request
- func (req *Request) SetResponseContentLengthPtr(contentLengthPtr *int64) *Request
- func (req *Request) SetResponseErrorBody(value interface{}) *Request
- func (req *Request) SetSuccessStatusCode(statusCodes ...int) *Request
- func (req *Request) SetTraceRequestBody(value bool) *Request
- func (req *Request) SetTraceResponseBody(value bool) *Request
- type Response
- type Trace
- type TraceMaker
Constants ¶
This section is empty.
Variables ¶
var (
ErrResponseNotUnmarshaled = errors.New("response was not unmarshaled")
)
Functions ¶
func IsJSONContentType ¶
func IsXMLContentType ¶
func JSONMarshal ¶
func JSONUnmarshal ¶
func XMLMarshal ¶
func XMLUnmarshal ¶
Types ¶
type Client ¶
type Client struct {
BaseURL string
ResponseBodyLimit int64
TraceBodies bool
ContentType string
Authorization string
ErrorType reflect.Type
Overridable Overridables
// contains filtered or unexported fields
}
func NewWithClient ¶
func NewWithTimeout ¶
func (*Client) NewRequest ¶
NewRequest is a shortcut for NewRequestWithContext(context.Background()).
func (*Client) NewRequestWithContext ¶ added in v0.0.11
NewRequestWithContext creates a new Request instance and initializes its fields with default values. It also sets the Content-Type and Authorization headers of the request if they are provided in the Client struct.
func (*Client) SetAuthorization ¶
func (*Client) SetBaseURL ¶
func (*Client) SetBasicAuth ¶
func (*Client) SetBearerAuth ¶
func (*Client) SetContentType ¶
func (*Client) SetContentTypeJSON ¶
func (*Client) SetContentTypeXML ¶
func (*Client) SetErrorBodyType ¶
func (*Client) SetResponseBodyLimit ¶
func (*Client) SetTraceBodies ¶
func (*Client) SetTraceMaker ¶
func (c *Client) SetTraceMaker(traceMaker TraceMaker) *Client
type HTTPDoer ¶
func MockHTTPDoer ¶
func MockHTTPDoer(p *MockHTTPResponse, additionalHeaders ...string) HTTPDoer
type MockHTTPResponse ¶
type MockHTTPResponse struct {
StatusCode int
Body []byte
BodyString string
BodyReader io.Reader
ContentType string
Error error
CapturedRequest *Request
}
func MockJSONResponse ¶
func MockJSONResponse(statusCode int, body string) *MockHTTPResponse
func MockJSONResponseFromFile ¶
func MockJSONResponseFromFile(t *testing.T, statusCode int, filePath string) *MockHTTPResponse
func MockXMLResponse ¶
func MockXMLResponse(statusCode int, body string) *MockHTTPResponse
func MockXMLResponseFromFile ¶
func MockXMLResponseFromFile(t *testing.T, statusCode int, filePath string) *MockHTTPResponse
type Overridables ¶
type Overridables struct {
Do Doer
DoHTTPRequest HTTPDoer
IsSuccess func(req *Request) bool
JSONMarshal func(req *Request, v interface{}) ([]byte, error)
JSONUnmarshal func(req *Request, data []byte, v interface{}) error
XMLMarshal func(req *Request, v interface{}) ([]byte, error)
XMLUnmarshal func(req *Request, data []byte, v interface{}) error
}
type Request ¶
type Request struct {
Client *Client
Context context.Context
Raw *http.Request
Method string
Path string
Header http.Header
Query url.Values
Body interface{}
BodyBytes []byte
ContentLength int64
Response Response
Overridable Overridables
TraceBody bool
}
func (*Request) ContentType ¶
func (*Request) ForceResponseJSON ¶
func (*Request) ForceResponseXML ¶
func (*Request) SetAuthorization ¶
func (*Request) SetBasicAuth ¶
func (*Request) SetBearerAuth ¶
func (*Request) SetContentLength ¶ added in v0.0.7
func (*Request) SetContentType ¶
func (*Request) SetContentTypeJSON ¶
func (*Request) SetContentTypeXML ¶
func (*Request) SetHeaderIf ¶
func (*Request) SetQueryParam ¶
func (*Request) SetQueryParamIf ¶
func (*Request) SetResponseBody ¶
func (*Request) SetResponseBodyLimit ¶
func (*Request) SetResponseContentLengthPtr ¶ added in v0.0.6
func (*Request) SetResponseErrorBody ¶
func (*Request) SetSuccessStatusCode ¶
func (*Request) SetTraceRequestBody ¶
func (*Request) SetTraceResponseBody ¶
type Response ¶
type Response struct {
Raw *http.Response
Error error
Body interface{}
ErrorBody interface{}
ForceJSON bool
ForceXML bool
BodyBytes []byte
BodyLimit int64
TraceBody bool
DoUnmarshal bool
ContentLengthPtr *int64
SuccessStatusCodes []int
}
func (*Response) ContentType ¶
func (*Response) HasEmptyBody ¶
func (*Response) StatusCode ¶
func (*Response) WantsRawByteArray ¶
func (*Response) WantsReadCloser ¶ added in v0.0.4
type Trace ¶
type Trace interface {
// OnAfterRequest is called just after a request was executed.
// It is called any time, even if the request/response was not
// successful.
OnAfterRequest(req *Request)
// End is called with defer, just after the trace has been created.
// It can be used to end/close a trace.
End()
}
Trace is created for each new request.
type TraceMaker ¶
type TraceMaker interface {
// NewTrace is called just before a request is about to be executed
// by the HTTP client. NewTrace is NOT called, if a request could not
// be built, for example because the request body could be marshaled.
NewTrace(req *Request) Trace
}
TraceMaker defines an interface for handling traces of HTTP requests. The interface is designed with Open Telemetry in mind. vrest creates a new trace for each request. A trace is only created, if the request could be built successfully.
A TraceMaker/Trace has full access to all Request data, but it should not modify anything. You can access the BodyBytes of the request and response if they are available. If the Request uses a Reader, BodyBytes will be nil.
Source Files
Directories