rapi

README

rAPI

rAPI is a Go (Golang) package that simplifies building and consuming RESTful APIs. It provides an HTTP handler for creating APIs and a client for making API requests.

Installation

You can install rAPI using the go get command:

go get github.com/goinsane/rapi

Contributing

Contributions are welcome! If you find a bug or want to add a feature, please open an issue or create a pull request.

License

This project is licensed under the BSD License.

Documentation

Index

• type CallOption
  • func WithAdditionalRequestHeader(header ...http.Header) CallOption
  • func WithErrOut(errOut error) CallOption
  • func WithForceBody(forceBody bool) CallOption
  • func WithMaxResponseBodySize(maxResponseBodySize int64) CallOption
  • func WithRequestHeader(header ...http.Header) CallOption
• type Caller
  • func (c *Caller) Call(ctx context.Context, in interface{}, opts ...CallOption) (result *Response, err error)
• type DoFunc
• type Factory
  • func NewFactory(client *http.Client, u *url.URL, opts ...CallOption) (f *Factory)
  • func (f *Factory) Caller(endpoint string, method string, out interface{}, opts ...CallOption) *Caller
• type Handler
  • func NewHandler(opts ...HandlerOption) (h *Handler)
  • func (h *Handler) Handle(pattern string, opts ...HandlerOption) Registrar
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerOption
  • func WithAllowEncoding(allowEncoding bool) HandlerOption
  • func WithMaxRequestBodySize(maxRequestBodySize int64) HandlerOption
  • func WithMiddleware(middleware ...MiddlewareFunc) HandlerOption
  • func WithOnError(onError func(error, *http.Request)) HandlerOption
  • func WithReadTimeout(readTimeout time.Duration) HandlerOption
  • func WithWriteTimeout(writeTimeout time.Duration) HandlerOption
• type HeaderOption
  • func ParseHeaderOptions(directive string) (options []HeaderOption)
• type HeaderOptionKeyVal
• type InvalidContentTypeError
  • func (e *InvalidContentTypeError) ContentType() string
  • func (e *InvalidContentTypeError) Error() string
• type MiddlewareFunc
• type Registrar
• type Request
• type RequestError
  • func (e *RequestError) Error() string
• type Response
• type SendFunc

Types

type CallOption

type CallOption interface {
	// contains filtered or unexported methods
}

CallOption configures how we set up the http call.

func WithAdditionalRequestHeader

func WithAdditionalRequestHeader(header ...http.Header) CallOption

WithAdditionalRequestHeader returns a CallOption that adds the given http headers to the request headers.

func WithErrOut

func WithErrOut(errOut error) CallOption

WithErrOut returns a CallOption that defines the error output to return as Caller.Call error.

func WithForceBody

func WithForceBody(forceBody bool) CallOption

WithForceBody returns a CallOption that forces sending input in the request body for all methods including HEAD and GET.

func WithMaxResponseBodySize

func WithMaxResponseBodySize(maxResponseBodySize int64) CallOption

WithMaxResponseBodySize returns a CallOption that limits maximum response body size.

func WithRequestHeader

func WithRequestHeader(header ...http.Header) CallOption

WithRequestHeader returns a CallOption that sets the given http headers to the request headers.

type Caller

type Caller struct {
	// contains filtered or unexported fields
}

Caller is the HTTP requester to do JSON requests with the given method to the given endpoint. The method and endpoint are given from Factory.

func (*Caller) Call

func (c *Caller) Call(ctx context.Context, in interface{}, opts ...CallOption) (result *Response, err error)

Call does the HTTP request with the given input and CallOption's.

type DoFunc

type DoFunc func(req *Request, send SendFunc)

DoFunc is a function type to process requests from Handler.

type Factory

type Factory struct {
	// contains filtered or unexported fields
}

Factory is Caller factory to create new Caller's.

func NewFactory

func NewFactory(client *http.Client, u *url.URL, opts ...CallOption) (f *Factory)

NewFactory creates a new Factory.

func (*Factory) Caller

func (f *Factory) Caller(endpoint string, method string, out interface{}, opts ...CallOption) *Caller

Caller creates a new Caller with the given endpoint and method.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler implements http.Handler to process JSON requests based on pattern and registered methods. Handler is similar to http.ServeMux in terms of operation.

func NewHandler

func NewHandler(opts ...HandlerOption) (h *Handler)

NewHandler creates a new Handler by given HandlerOption's.

func (*Handler) Handle

func (h *Handler) Handle(pattern string, opts ...HandlerOption) Registrar

Handle creates a Registrar to register methods for the given pattern.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is implementation of http.Handler.

type HandlerOption

type HandlerOption interface {
	// contains filtered or unexported methods
}

HandlerOption sets options such as middleware, read timeout, etc.

func WithAllowEncoding

func WithAllowEncoding(allowEncoding bool) HandlerOption

WithAllowEncoding returns a HandlerOption that allows encoded content types such as gzip to be returned. By default, encoding is allowed.

func WithMaxRequestBodySize

func WithMaxRequestBodySize(maxRequestBodySize int64) HandlerOption

WithMaxRequestBodySize returns a HandlerOption that limits maximum request body size.

func WithMiddleware

func WithMiddleware(middleware ...MiddlewareFunc) HandlerOption

WithMiddleware returns a HandlerOption that adds middlewares.

func WithOnError

func WithOnError(onError func(error, *http.Request)) HandlerOption

WithOnError returns a HandlerOption that sets the function to be called on error.

func WithReadTimeout

func WithReadTimeout(readTimeout time.Duration) HandlerOption

WithReadTimeout returns a HandlerOption that limits maximum request body read duration.

func WithWriteTimeout

func WithWriteTimeout(writeTimeout time.Duration) HandlerOption

WithWriteTimeout returns a HandlerOption that limits maximum response body write duration.

type HeaderOption

type HeaderOption struct {
	KeyVals []HeaderOptionKeyVal
	Map     map[string]string
}

func ParseHeaderOptions

func ParseHeaderOptions(directive string) (options []HeaderOption)

type HeaderOptionKeyVal

type HeaderOptionKeyVal struct {
	Key string
	Val string
}

type InvalidContentTypeError

type InvalidContentTypeError struct {
	// contains filtered or unexported fields
}

InvalidContentTypeError occurs when the request or response body content type is invalid.

func (*InvalidContentTypeError) ContentType

func (e *InvalidContentTypeError) ContentType() string

ContentType returns the invalid content type.

func (*InvalidContentTypeError) Error

func (e *InvalidContentTypeError) Error() string

Error is the implementation of error.

type MiddlewareFunc

type MiddlewareFunc func(req *Request, send SendFunc, do DoFunc)

MiddlewareFunc is a function type to process requests as middleware from Handler.

type Registrar

type Registrar interface {
	// Register registers method with the given parameters to Handler. The pattern was given from Handler.Handle.
	Register(method string, in interface{}, do DoFunc, opts ...HandlerOption) Registrar
}

Registrar is method registrar and created by Handler.Handle.

type Request

type Request struct {
	*http.Request
	Data []byte
	In   interface{}
}

Request encapsulates http.Request and gives input from request. It is used in DoFunc and MiddlewareFunc.

type RequestError

type RequestError struct {
	// contains filtered or unexported fields
}

RequestError is the request error from http.Client. It is returned from Caller.Call.

func (*RequestError) Error

func (e *RequestError) Error() string

Error is the implementation of error.

type Response

type Response struct {
	*http.Response
	Data []byte
	Out  interface{}
}

Response encapsulates http.Response and gives data and output from response. It is returned from Caller.Call.

type SendFunc

type SendFunc func(out interface{}, code int, header ...http.Header)

SendFunc is a function type to send response in DoFunc or MiddlewareFunc.