api

Documentation

Overview

Package api is the atomic api helper library

Index

• func Log(ctx context.Context) log.Interface
• func Request(ctx context.Context) (*http.Request, http.ResponseWriter)
• func RequestBody(ctx context.Context) []byte
• func RequestHost(ctx context.Context) string
• type Authorizer
• type ContextFunc
• type EncodeFunc
• type Encoder
• type Option
  • func WithAddr(addr string) Option
  • func WithBasepath(base string) Option
  • func WithCORS(origin ...string) Option
  • func WithCache(ttl time.Duration) Option
  • func WithListener(l net.Listener) Option
  • func WithLog(l log.Interface) Option
  • func WithName(name string) Option
  • func WithRouter(router *mux.Router) Option
  • func WithVersioning(version string, serverVersion ...string) Option
• type Parameters
• type RedirectError
• type Responder
• type Response
  • func Error(e error) *Response
  • func ErrorRedirect(r RedirectError) *Response
  • func Errorf(f string, args ...interface{}) *Response
  • func NewResponse(payload ...interface{}) *Response
  • func Redirect(u *url.URL, args ...map[string]string) *Response
  • func StatusError(status int, e error) *Response
  • func StatusErrorf(status int, f string, args ...interface{}) *Response
  • func (r *Response) Payload() interface{}
  • func (r *Response) Status() int
  • func (r *Response) WithHeader(key string, value string) *Response
  • func (r *Response) WithHeaders(h map[string]interface{}) *Response
  • func (r *Response) WithStatus(status int) *Response
  • func (r *Response) Write(w http.ResponseWriter, req *http.Request) error
• type RouteOption
  • func WithAuthorizers(a ...Authorizer) RouteOption
  • func WithCaching() RouteOption
  • func WithContextFunc(f ContextFunc) RouteOption
  • func WithMethod(m string) RouteOption
  • func WithParams(p interface{}) RouteOption
  • func WithValidation(v bool) RouteOption
• type Server
  • func NewServer(opts ...Option) *Server
  • func (s *Server) AddRoute(path string, handler interface{}, opts ...RouteOption)
  • func (s *Server) Handler() http.Handler
  • func (s *Server) Log() log.Interface
  • func (s *Server) LogMiddleware() func(http.Handler) http.Handler
  • func (s *Server) RequestVersion(r *http.Request) string
  • func (s *Server) Router() *mux.Router
  • func (s *Server) Serve() error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) WriteError(w http.ResponseWriter, status int, err error)
  • func (s *Server) WriteJSON(w http.ResponseWriter, status int, v interface{}, pretty ...bool)

Functions

func Log

func Log(ctx context.Context) log.Interface

Log returns the logger

func Request

func Request(ctx context.Context) (*http.Request, http.ResponseWriter)

Request gets the reqest and response objects from the context

func RequestBody

func RequestBody(ctx context.Context) []byte

RequestBody returns the raw request body

func RequestHost

func RequestHost(ctx context.Context) string

RequestHost returns the host from the current request

Types

type Authorizer

type Authorizer func(r *http.Request) (context.Context, error)

Authorizer performs an autorization and returns a context or error on failure

type ContextFunc

type ContextFunc func(context.Context) context.Context

ContextFunc adds context to a request

type EncodeFunc

type EncodeFunc func(w io.Writer) error

EncodeFunc encodes the payload

type Encoder

type Encoder interface {
	Encode(w io.Writer) error
}

Encoder is a response encoder

type Option

type Option func(*Server)

Option provides the server options, these will override th defaults and any atomic instance values.

func WithAddr

func WithAddr(addr string) Option

WithAddr sets the listen address for the server

func WithBasepath

func WithBasepath(base string) Option

WithBasepath sets the router basepath for the api

func WithCORS

func WithCORS(origin ...string) Option

WithCORS sets the cors origin and enables cors on the router

func WithCache

func WithCache(ttl time.Duration) Option

WithCache enables content caching for the route

func WithListener

func WithListener(l net.Listener) Option

WithListener sets the net listener for the server

func WithLog

func WithLog(l log.Interface) Option

WithLog specifies a new logger

func WithName

func WithName(name string) Option

WithName specifies the server name

func WithRouter

func WithRouter(router *mux.Router) Option

WithRouter specifies the router to use

func WithVersioning

func WithVersioning(version string, serverVersion ...string) Option

WithVersioning enables versioning that will enforce a versioned path and optionally set the Server header to the serverVersion

type Parameters

type Parameters interface {
	Validate() error
}

Parameters interface handles binding requests

type RedirectError

type RedirectError struct {
	URL            *url.URL
	Status         int
	Err            string
	ErrDescription string
}

RedirectError is used to redirect it the url is valid

type Responder

type Responder interface {
	// Status returns the http status
	Status() int

	// Payload is the payload
	Payload() interface{}

	// Write writes ou the payload
	Write(w http.ResponseWriter, r *http.Request) error
}

Responder is an api response interface

type Response

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

Response is the common response type

func Error

func Error(e error) *Response

Error returns an error responder

func ErrorRedirect

func ErrorRedirect(r RedirectError) *Response

ErrorRedirect does a redirect if there is a url otherwise returns the error directly

func Errorf

func Errorf(f string, args ...interface{}) *Response

Errorf returns a new error response from a string

func NewResponse

func NewResponse(payload ...interface{}) *Response

NewResponse returns a response with defaults

func Redirect

func Redirect(u *url.URL, args ...map[string]string) *Response

Redirect will set the proper redirect headers and http.StatusFound

func StatusError

func StatusError(status int, e error) *Response

StatusError sets the status and error message in one go

func StatusErrorf

func StatusErrorf(status int, f string, args ...interface{}) *Response

StatusErrorf sets the status and error message in one go

func (*Response) Payload

func (r *Response) Payload() interface{}

Payload returns the payload

func (*Response) Status

func (r *Response) Status() int

Status returns the status

func (*Response) WithHeader

func (r *Response) WithHeader(key string, value string) *Response

WithHeader adds headers to the request

func (*Response) WithHeaders

func (r *Response) WithHeaders(h map[string]interface{}) *Response

WithHeaders adds a map of header values

func (*Response) WithStatus

func (r *Response) WithStatus(status int) *Response

WithStatus sets the status

func (*Response) Write

func (r *Response) Write(w http.ResponseWriter, req *http.Request) error

Write writes the response to the writer

type RouteOption

type RouteOption func(*routeOption)

RouteOption defines route options

func WithAuthorizers

func WithAuthorizers(a ...Authorizer) RouteOption

WithAuthorizers sets the authorizers

func WithCaching

func WithCaching() RouteOption

WithCaching enables content caching for the route

func WithContextFunc

func WithContextFunc(f ContextFunc) RouteOption

WithContextFunc sets the context handler for the route option

func WithMethod

func WithMethod(m string) RouteOption

WithMethod sets the method for the route option

func WithParams

func WithParams(p interface{}) RouteOption

WithParams sets the params for the route option

func WithValidation

func WithValidation(v bool) RouteOption

WithValidation sets the parameter validation

type Server

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

Server is an http server that provides basic REST funtionality

func NewServer

func NewServer(opts ...Option) *Server

NewServer creates a new server object

func (*Server) AddRoute

func (s *Server) AddRoute(path string, handler interface{}, opts ...RouteOption)

AddRoute adds a route in the clear

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the server http handler

func (*Server) Log

func (s *Server) Log() log.Interface

Log returns the server log

func (*Server) LogMiddleware

func (s *Server) LogMiddleware() func(http.Handler) http.Handler

LogMiddleware is simple logging middleware handler

func (*Server) RequestVersion

func (s *Server) RequestVersion(r *http.Request) string

RequestVersion returns the request version or the server version is not found

func (*Server) Router

func (s *Server) Router() *mux.Router

Router returns the server router

func (*Server) Serve

func (s *Server) Serve() error

Serve starts the http server

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown shuts down the http server with the context

func (*Server) WriteError

func (s *Server) WriteError(w http.ResponseWriter, status int, err error)

WriteError writes an error object

func (*Server) WriteJSON

func (s *Server) WriteJSON(w http.ResponseWriter, status int, v interface{}, pretty ...bool)

WriteJSON writes out json