api

README

API package documentation

The api package implements the API layer of the application, providing a structured approach to manage HTTP servers, routes, handlers, and request/response mappings.

Components

Server

The Server struct manages the lifecycle of the HTTP server. It is responsible for:

• Listening for incoming requests.
• Serving responses via the http.Server.
• Gracefully shutting down the server when required.

This component is highly configurable, allowing you to set:

• Server address and port.
• Read and write timeouts.

Router

The default router is based on the lightweight Chi router, which can be replaced with any router implementing the http.Handler interface.

Features:

• Route Initialization: Configures application routes and middleware.
• Centralized Error Handling: Provides a unified approach for managing errors across routes.

Handler

The Handler struct serves as a generic interface for handling incoming HTTP requests. It decouples business logic from the HTTP layer by:

• Validating and passing the request's context and inputs to the service functions.
• Returning a response or error from the service functions.

How to Use:

• Create a New Handler
• Initialize Endpoints

Mappers

The Mappers struct simplifies the process of translating HTTP requests into service-layer inputs and mapping service outputs to HTTP responses.

Key Features:

• No need to create new handlers for each endpoint.
• Implement the following interfaces for custom mappings:
  • RequestMapper
  • ResponseMapper

Examples:
The mappers package includes examples for handling various types of requests and responses.

Documentation

Index

• type Error
  • func (e Error) Error() string
• type Handler
  • func NewHandler[In any, Out any](reqMapper RequestMapper[In], resMapper ResponseMapper[Out], ...) Handler[In, Out]
  • func (h Handler[In, Out]) Handle(w http.ResponseWriter, r *http.Request) error
  • func (h Handler[In, Out]) Route(router *Router, method, path string)
• type HandlerFunc
• type RequestMapper
• type ResponseMapper
• type Router
  • func NewRouter(cfg *config.Config) *Router
  • func (r *Router) HttpHandlerFunc(h HandlerFunc[any, any]) http.HandlerFunc
• type Server
  • func NewServer(cfg config.HTTPConfig) *Server
  • func (s *Server) Run(api http.Handler) error
  • func (s *Server) Shutdown(ctx context.Context) error
• type ServiceFunc
• type Validator

Types

type Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Cause   error  `json:"-"`
}

func (Error) Error

func (e Error) Error() string

type Handler

type Handler[In any, Out any] struct {
	// contains filtered or unexported fields
}

Handler is a generic handler type.

func NewHandler

func NewHandler[In any, Out any](
	reqMapper RequestMapper[In],
	resMapper ResponseMapper[Out],
	svcFunc ServiceFunc[In, Out],
	vld Validator,
) Handler[In, Out]

NewHandler creates new handler.

func (Handler[In, Out]) Handle

func (h Handler[In, Out]) Handle(w http.ResponseWriter, r *http.Request) error

Handle handles the http request. No need to write a separate handler for each endpoint. Just create request and response mappers and use this generic handler. It will map the request, validate it, call the service function and map the response. It will return an error if any of the steps fail. Assumes that the service function receives context and input type, and returns a output object and an error.

func (Handler[In, Out]) Route

func (h Handler[In, Out]) Route(router *Router, method, path string)

Route registers the handler with the router.

type HandlerFunc

type HandlerFunc[In any, Out any] func(http.ResponseWriter, *http.Request) error

HandlerFunc is API generic handler func type.

type RequestMapper

type RequestMapper[In any] interface {
	Map(*http.Request) (In, error)
}

RequestMapper is generic interfaces for mapping request objects.

type ResponseMapper

type ResponseMapper[Out any] interface {
	Map(http.ResponseWriter, Out) error
}

ResponseMapper is generic interfaces for mapping response objects.

type Router

type Router struct {
	chi.Router
	// contains filtered or unexported fields
}

Router is the main API router. It is a wrapper around chi.Router with some additional functionality. Chi router can be replaced with any other router that implements net/http.

func NewRouter

func NewRouter(cfg *config.Config) *Router

func (*Router) HttpHandlerFunc

func (r *Router) HttpHandlerFunc(h HandlerFunc[any, any]) http.HandlerFunc

HttpHandlerFunc creates http.HandlerFunc from custom HandlerFunc. It handles API errors and returns them as HTTP errors.

type Server

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

func NewServer

func NewServer(cfg config.HTTPConfig) *Server

NewServer creates a new Server.

func (*Server) Run

func (s *Server) Run(api http.Handler) error

Run starts the server and listens for incoming requests.

func (*Server) Shutdown

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

Shutdown gracefully shuts down the server without interrupting any active connections.

type ServiceFunc

type ServiceFunc[In any, Out any] func(context.Context, In) (Out, error)

ServiceFunc is a generic service function type called in a handler.

type Validator

type Validator interface {
	StructCtx(ctx context.Context, s interface{}) (err error)
}