apis

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

• func MakeHTTPHandleFunc(fnc APIFunc) http.HandlerFunc
• func ReturnErrorJSON(w *http.ResponseWriter, status int, message string) (err error)
• func WriteJSON(w *http.ResponseWriter, status int, v any) (err error)
• type APIFunc
• type ErrorStruct
• type MiddlewareController
  • func NewMiddlwareController() (mc *MiddlewareController, err error)
  • func (mc *MiddlewareController) Blacklisted(ipaddr string) (err error)

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 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 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

	// 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
}

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() (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.