api

Documentation

Overview

Package api exposes the main API engine. All HTTP APIs are handled here - so-called "business logic" should be here, or in a dedicated package (if that logic is complex enough).

To use this package, you should create a new instance with New() passing a valid Config. The resulting Router will have the Router.Handler() function that returns a handler that can be used in a http.Server (or in other middlewares).

Example:

// Create the API router
apirouter, err := api.New(api.Config{
	Logger:   logger,
	Database: appdb,
})
if err != nil {
	logger.WithError(err).Error("error creating the API server instance")
	return fmt.Errorf("error creating the API server instance: %w", err)
}
router := apirouter.Handler()

// ... other stuff here, like middleware chaining, etc.

// Create the API server
apiserver := http.Server{
	Addr:              cfg.Web.APIHost,
	Handler:           router,
	ReadTimeout:       cfg.Web.ReadTimeout,
	ReadHeaderTimeout: cfg.Web.ReadTimeout,
	WriteTimeout:      cfg.Web.WriteTimeout,
}

// Start the service listening for requests in a separate goroutine
apiserver.ListenAndServe()

See the `main.go` file inside the `cmd/webapi` for a full usage example.

Index

• type Config
• type Router
  • func New(cfg Config) (Router, error)

Types

type Config

type Config struct {
	// Logger where log entries are sent
	Logger logrus.FieldLogger

	// Database is the instance of database.AppDatabase where data are saved
	Database database.AppDatabase
}

Config is used to provide dependencies and configuration to the New function.

type Router

type Router interface {
	// Handler returns an HTTP handler for APIs provided in this package
	Handler() http.Handler

	// Close terminates any resource used in the package
	Close() error
}

Router is the package API interface representing an API handler builder

func New

func New(cfg Config) (Router, error)

New returns a new Router instance