apis

README

APIs

Overview

This package is designed to aid developers in creating APIs in Golang. There are various generic functions that can be utilized, along with a generic middleware object. The middleware allows the user to create IP blacklists, set a built-in authorization function that gets checked prior to sending the request to the router, log request events and more.

Documentation

Overview

package that provides general functions, types, structs, etc. that can be used when creating an API or HTTP server.

inspiration for adding/based on: https://www.youtube.com/watch?v=pwZuNmAzaH8

Index

• Constants
• func MakeHTTPHandleFunc(fnc APIFunc) http.HandlerFunc
• func ReturnErrorJSON(w *http.ResponseWriter, status int, message string) (err error)
• func WithColoring(mo *MiddlewareOptions) (err error)
• func WithLogging(mo *MiddlewareOptions) (err error)
• func WriteJSON(w *http.ResponseWriter, status int, v any) (err error)
• type APIFunc
• type AuthFunc
• type ErrorStruct
• type MiddlewareController
  • func NewMiddlwareController(optsfuncs ...MiddlewareOptsFunc) (mc *MiddlewareController, err error)
  • func (mc *MiddlewareController) Blacklisted(ipaddr string) (err error)
  • func (mc *MiddlewareController) LogEvent(message string, severity int)
  • func (mc *MiddlewareController) MakeHTTPHandleFunc(fnc APIFunc) http.HandlerFunc
• type MiddlewareOptions
• type MiddlewareOptsFunc
  • func WithAuthorization(af AuthFunc) MiddlewareOptsFunc

Constants

const EVENT_ERROR int = 1

logging level that indicates the event is an error event.

const EVENT_INFO int = 0

logging level that indicates the event is a log event.

const EVENT_SUCCESS int = 2

logging level that indicates the event is a success event.

const EVENT_WARNING int = 3

logging level that indicates the event is a warning event.

Functions

func MakeHTTPHandleFunc

func MakeHTTPHandleFunc(fnc APIFunc) http.HandlerFunc

function designed to more elegantly handle HTTP routing functions. this is, essentially, a middleware controller that extends the HandleFunc function. this takes an APIFunc as an argument and processes it.

func ReturnErrorJSON

func ReturnErrorJSON(w *http.ResponseWriter, status int, message string) (err error)

function designed to return an error JSON payload to the client. this can be passed to MakeHTTPHandleFunc and used if/when an issue occurs during the execution of an API endpoint.

func WithColoring

func WithColoring(mo *MiddlewareOptions) (err error)

function designed to set the Coloring flag of a MiddlewareOptions object. this will set the Coloring variable to true. when the flag is set, the output will change color based on the severity of the event.

func WithLogging

func WithLogging(mo *MiddlewareOptions) (err error)

function designed to set the Logging flag of a MiddlewareOptions object. this will set the Logging variable to true.

func WriteJSON

func WriteJSON(w *http.ResponseWriter, status int, v any) (err error)

function designed to handle writing a JSON payload to an HTTP response.

if there is an issue encountered while encoding the JSON payload, the error will be returned, otherwise nil will be returned.

Types

type APIFunc

type APIFunc func(http.ResponseWriter, *http.Request) error

alias of http request function that returns an error. this will be handled by middleware and is used for more control/neater code.

type AuthFunc

type AuthFunc func(*http.Request) error

alias of a function that is used to authenticate a user. this will be handled by the middleware and is used to allow/restrict a user from accessing the API's endpoints.

type ErrorStruct

type ErrorStruct struct {
	// the code associated with the given error.
	ErrorCode int `json:"code"`

	// a message detailing the error that has been thrown.
	ErrorMessage string `json:"message"`
}

struct designed to represent a JSON error return that can be used to deliver information about an error that has been thrown during execution of an API/Server function.

type MiddlewareController

type MiddlewareController struct {

	// slice holding IP addresses that are blacklisted. these
	// can be used to restrict who can contact the API.
	AddressBlacklist []string

	// authorization function (if any) to be used by the
	// middleware to restrict access to the endpoints.
	AuthorizationFunction AuthFunc

	// slice holding all the headers reuqired for a request to
	// be properly handled by the API. this is meant to be a list
	// that all endpoints require and not meant to be specific
	// to a single endpoint.
	RequiredHeaders []string
	// contains filtered or unexported fields
}

structure designed to represent a middleware controller that can be used to filter requests to the API. this will include various generic settings that can be controlled by the user.

func NewMiddlwareController

func NewMiddlwareController(optsfuncs ...MiddlewareOptsFunc) (mc *MiddlewareController, err error)

function designed to create and return a new MiddlwareController object to the user. this will return a pointer to the new MiddlwareController and an error. if the creation is successful, nil will be returned in place of an error.

func (*MiddlewareController) Blacklisted

func (mc *MiddlewareController) Blacklisted(ipaddr string) (err error)

function designed to check if a given IP address string is in the AddressBlacklist slice for the middleware. if the blacklist contains the given IP address nil will be returned, otherwise an error will be returned.

the address comparison is case-insensitive.

func (*MiddlewareController) LogEvent

func (mc *MiddlewareController) LogEvent(message string, severity int)

function designed to log a middleware event.

func (*MiddlewareController) MakeHTTPHandleFunc

func (mc *MiddlewareController) MakeHTTPHandleFunc(fnc APIFunc) http.HandlerFunc

function designed to more elegantly handle HTTP routing functions. this is, essentially, a middleware controller that extends the HandleFunc function. this takes an APIFunc as an argument and processes it.

type MiddlewareOptions

type MiddlewareOptions struct {

	// authorization function (if any) to be used by the
	// middleware to restrict access to the endpoints.
	AuthorizationFunction AuthFunc

	// flag to set logging on/off
	Logging bool

	// flag to set coloring for logging output.
	Coloring bool
}

strucuture designed to hold the various options available for a MiddlewareController.

type MiddlewareOptsFunc

type MiddlewareOptsFunc func(*MiddlewareOptions) error

alias of a function that is used to manipulate the various parts of a MiddlewareOptions object.

func WithAuthorization

func WithAuthorization(af AuthFunc) MiddlewareOptsFunc

function designed to set the authorization function of a MiddlewareOptions object. this will be assigned to the MiddlewareController that processes the MiddlewareOptions struct.