apimanager

README

go-kit/apimanager - API Manager Module

• About this module
• Installation
• Usage
• Code of Conduct
• Working Language
• Support and Feedback
• How to Contribute
• Licensing

You can use the apimanager module to manage APIs in your Go application.

About this module

This module provides a simple way to manage an API server with the ability to add routes, route-groups, and middlewares. It is built on top of the gofiber/fiber framework.

Additionally, it provides several packages with common utilities to manage APIs, such as:

• apimanager: The main package to manage APIs.
• apimanager/middleware: A package with common middlewares.
• apimanager/fiberutils: A package with utilities to work with the Fiber framework. This includes request and response utilities, as well as generic parsers that can be used in combination with the request utilities.

Installation

To install, run:

go get github.com/lvlcn-t/go-kit/apimanager

And import the package in your code:

import (
    "github.com/lvlcn-t/go-kit/apimanager"
    "github.com/lvlcn-t/go-kit/apimanager/middleware"
    "github.com/lvlcn-t/go-kit/apimanager/fiberutils"
)

Usage

The documentation for this module can be found on pkg.go.dev.

To see how to use this module, you can check the examples directory of the repository.

Code of Conduct

This project has adopted the Contributor Covenant in version 2.1 as our code of conduct. Please see the details in our CODE_OF_CONDUCT.md. All contributors must abide by the code of conduct.

Working Language

We decided to apply English as the primary project language.

Consequently, all content will be made available primarily in English. We also ask all interested people to use English as the preferred language to create issues, in their code (comments, documentation, etc.) and when you send requests to us. The application itself and all end-user facing content will be made available in other languages as needed.

Support and Feedback

The following channels are available for discussions, feedback, and support requests:

Type	Channel
Issues

How to Contribute

Contribution and feedback is encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright (c) 2024 lvlcn-t.

Licensed under the MIT (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at https://www.mit.edu/~amini/LICENSE.md.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE for the specific language governing permissions and limitations under the License.

Documentation

Overview

Package apimanager provides a way to create and manage API servers.

Example

server := apimanager.New(nil)
err := server.Mount(apimanager.Route{
	Path:    "/",
	Methods: []string{fiber.MethodGet},
	Handler: func(c fiber.Ctx) error {
		return c.SendString("Hello, World!")
	},
})
if err != nil {
	fmt.Println(err)
	return
}

if err := server.Run(context.Background()); err != nil {
	panic(err)
}

Index

• Constants
• func OkHandler(c fiber.Ctx) error
• type Config
  • func (c *Config) IsEmpty() bool
  • func (c *Config) Validate() error
• type ErrAlreadyRunning
  • func (e *ErrAlreadyRunning) Error() string
  • func (e *ErrAlreadyRunning) Is(target error) bool
• type ErrNotRunning
  • func (e *ErrNotRunning) Error() string
  • func (e *ErrNotRunning) Is(target error) bool
• type Route
  • func Delete(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route
  • func Get(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route
  • func Patch(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route
  • func Post(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route
  • func Put(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route
  • func Use(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route
• type RouteGroup
  • func NewRouteGroup(path string, app fiber.Router) RouteGroup
• type Server
  • func New(c *Config, middlewares ...fiber.Handler) Server
• type TLSConfig

Examples

• Package

Constants

const MethodUse = "USE"

MethodUse is a custom HTTP method to indicate that a route should be registered for all HTTP methods.

Functions

func OkHandler

func OkHandler(c fiber.Ctx) error

OkHandler is a handler that returns an HTTP 200 OK response.

Types

type Config

type Config struct {
	// Address is the address to listen on.
	Address string `yaml:"address" mapstructure:"address"`
	// BasePath is the base path of the API.
	BasePath string `yaml:"basePath" mapstructure:"basePath"`
	// UseDefaultHealthz indicates if the default healthz handler should be used.
	UseDefaultHealthz bool `yaml:"useDefaultHealthz" mapstructure:"useDefaultHealthz"`
	// TLS is the TLS configuration.
	TLS TLSConfig `yaml:"tls" mapstructure:"tls"`
}

Config is the configuration of the server.

func (*Config) IsEmpty

func (c *Config) IsEmpty() bool

IsEmpty checks if the configuration is empty.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the configuration.

type ErrAlreadyRunning

type ErrAlreadyRunning struct{}

ErrAlreadyRunning is an error that is returned when the server is already running.

func (*ErrAlreadyRunning) Error

func (e *ErrAlreadyRunning) Error() string

Error returns the error message.

func (*ErrAlreadyRunning) Is

func (e *ErrAlreadyRunning) Is(target error) bool

Is checks if the target error is an ErrAlreadyRunning error.

type ErrNotRunning

type ErrNotRunning struct{}

ErrNotRunning is an error that is returned when the server is not running.

func (*ErrNotRunning) Error

func (e *ErrNotRunning) Error() string

Error returns the error message.

func (*ErrNotRunning) Is

func (e *ErrNotRunning) Is(target error) bool

Is checks if the target error is an ErrNotRunning error.

type Route

type Route struct {
	// Path is the path of the route.
	Path string
	// Methods is the HTTP method of the route.
	// To register the route to all http methods, use [MethodUse].
	// [MethodUse] is mutually exclusive with other methods.
	Methods []string
	// Handler is the handler function of the route.
	Handler fiber.Handler
	// Middlewares are the middlewares to use for the route.
	Middlewares []fiber.Handler
}

Route is a route to register to the server.

func Delete

func Delete(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route

Delete creates a new Route with the provided path, handler, and middlewares for the http.MethodDelete method.

func Get

func Get(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route

Get creates a new Route with the provided path, handler, and middlewares for the http.MethodGet method.

func Patch

func Patch(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route

Patch creates a new Route with the provided path, handler, and middlewares for the http.MethodPatch method.

func Post

func Post(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route

Post creates a new Route with the provided path, handler, and middlewares for the http.MethodPost method.

func Put

func Put(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route

Put creates a new Route with the provided path, handler, and middlewares for the http.MethodPut method.

func Use

func Use(path string, handler fiber.Handler, middlewares ...fiber.Handler) Route

Use creates a new Route with the provided path, handler, and middlewares for all HTTP methods.

type RouteGroup

type RouteGroup struct {
	// Path is the Path of the route.
	Path string
	// App is the fiber sub-App to use.
	App fiber.Router
}

RouteGroup is a route to register a sub-app to.

func NewRouteGroup

func NewRouteGroup(path string, app fiber.Router) RouteGroup

NewRouteGroup creates a new RouteGroup with the provided path and sub-app.

type Server

type Server interface {
	// Run attaches all previously mounted routes and starts the server.
	// Runs indefinitely until an error occurs, the server shuts down, or the provided context is done.
	//
	// Example setup:
	// 	server := apimanager.New(nil)
	// 	server.Mount(apimanager.Get("/", func(c fiber.Ctx) error {
	// 		return c.SendString("Hello, World!")
	// 	}))
	// 	// The server will listen on the default address ":8080" and respond with "Hello, World!" on a GET request to "/".
	// 	server.Run(context.Background())
	Run(ctx context.Context) error
	// Restart restarts the server by shutting it down and starting it again.
	// If any routes or groups are provided, they will be added to the server.
	// All existing routes and groups will be preserved.
	Restart(ctx context.Context, routes []Route, groups []RouteGroup) error
	// Shutdown gracefully shuts down the server.
	Shutdown(ctx context.Context) error
	// Mount adds the provided routes to the server.
	Mount(routes ...Route) error
	// MountGroup adds the provided route groups to the server.
	MountGroup(groups ...RouteGroup) error
	// App returns the fiber app of the server.
	App() *fiber.App
	// Mounted returns all mounted routes, groups, and global middlewares.
	Mounted() (routes []Route, groups []RouteGroup, middlewares []fiber.Handler)
	// Config returns the configuration of the server.
	Config() Config
}

Server is the interface for an API server.

func New

func New(c *Config, middlewares ...fiber.Handler) Server

New creates a new server with the provided configuration and middlewares. If no configuration is provided, a default configuration will be used. If no middlewares are provided, a default set of middlewares will be used.

type TLSConfig

type TLSConfig struct {
	// Enabled indicates if TLS is enabled.
	Enabled bool `yaml:"enabled" mapstructure:"enabled"`
	// CertFile is the path to the certificate file.
	CertFile string `yaml:"certPath" mapstructure:"certPath"`
	// CertKeyFile is the path to the certificate key file.
	CertKeyFile string `yaml:"keyPath" mapstructure:"keyPath"`
}

TLSConfig is the TLS configuration.