apirest

Documentation

Index

• Constants
• type API
  • func NewAPI(router *httprouter.HTTProuter, baseRoute string) (*API, error)
  • func (a *API) AddAuthToken(bearerToken string, requests int64)
  • func (a *API) AuthorizeRequest(data any, accessType httprouter.AuthAccessType) (bool, error)
  • func (a *API) DelAuthToken(bearerToken string)
  • func (a *API) EnableVerboseAuthLog()
  • func (a *API) GetAuthTokens(bearerToken string) int64
  • func (a *API) ProcessData(req *http.Request) (any, error)
  • func (a *API) RegisterMethod(pattern, HTTPmethod string, accessType string, handler APIhandler) error
  • func (a *API) SetAdminToken(bearerToken string)
• type APIdata
• type APIerror
  • func (e APIerror) Error() string
  • func (e APIerror) MarshalJSON() ([]byte, error)
  • func (e APIerror) Send(ctx *httprouter.HTTPContext) error
  • func (e APIerror) With(s string) APIerror
  • func (e APIerror) WithErr(err error) APIerror
  • func (e APIerror) Withf(format string, args ...any) APIerror
• type APIhandler

Constants

const (
	// MethodAccessTypePrivate for private requests
	MethodAccessTypePrivate = "private"
	// MethodAccessTypeQuota for rate-limited quota requests
	MethodAccessTypeQuota = "quota"
	// MethodAccessTypePublic for public requests
	MethodAccessTypePublic = "public"
	// MethodAccessTypeAdmin for admin requests
	MethodAccessTypeAdmin = "admin"
)

const (
	HTTPstatusOK                 = http.StatusOK
	HTTPstatusNoContent          = http.StatusNoContent
	HTTPstatusBadRequest         = http.StatusBadRequest
	HTTPstatusInternalErr        = http.StatusInternalServerError
	HTTPstatusNotFound           = http.StatusNotFound
	HTTPstatusServiceUnavailable = http.StatusServiceUnavailable
)

HTTPstatus* equal http.Status*, simple sugar to avoid importing http everywhere

Types

type API

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

API is a namespace handler for the httpRouter with Bearer authorization

func NewAPI

func NewAPI(router *httprouter.HTTProuter, baseRoute string) (*API, error)

NewAPI returns an API initialized type

func (*API) AddAuthToken

func (a *API) AddAuthToken(bearerToken string, requests int64)

AddAuthToken adds a new bearer token capable to perform up to n requests

func (*API) AuthorizeRequest

func (a *API) AuthorizeRequest(data any, accessType httprouter.AuthAccessType) (bool, error)

AuthorizeRequest is a function for the RouterNamespace interface. On private handlers checks if the supplied bearer token have still request credits

func (*API) DelAuthToken

func (a *API) DelAuthToken(bearerToken string)

DelAuthToken removes a bearer token (will be not longer valid)

func (*API) EnableVerboseAuthLog

func (a *API) EnableVerboseAuthLog()

EnableVerboseAuthLog prints on stdout the details of every request performed with auth token. It can be used for keeping track of private/admin actions on a service.

func (*API) GetAuthTokens

func (a *API) GetAuthTokens(bearerToken string) int64

GetAuthTokens returns the number of pending requests credits for a bearer token

func (*API) ProcessData

func (a *API) ProcessData(req *http.Request) (any, error)

ProcessData processes the HTTP request and returns structured data. The body of the http requests and the bearer auth token are readed.

func (*API) RegisterMethod

func (a *API) RegisterMethod(pattern, HTTPmethod string, accessType string, handler APIhandler) error

RegisterMethod adds a new method under the URL pattern. The pattern URL can contain variable names by using braces, such as /send/{name}/hello The pattern can also contain wildcard at the end of the path, such as /send/{name}/hello/* The accessType can be of type private, public or admin.

func (*API) SetAdminToken

func (a *API) SetAdminToken(bearerToken string)

SetAdminToken sets the bearer admin token capable to execute admin handlers

type APIdata

type APIdata struct {
	Data      []byte
	AuthToken string
}

APIdata is the data type used by the API. On handler functions Message.Data can be cast safely to this type.

type APIerror

type APIerror struct {
	Err        error
	Code       int
	HTTPstatus int
}

APIerror is used by handler functions to wrap errors, assigning a unique error code and also specifying which HTTP Status should be used.

func (APIerror) Error

func (e APIerror) Error() string

Error returns the Message contained inside the APIerror

func (APIerror) MarshalJSON

func (e APIerror) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON containing Err.Error() and Code. Field HTTPstatus is ignored.

Example output: {"error":"account not found","code":4003}

func (APIerror) Send

func (e APIerror) Send(ctx *httprouter.HTTPContext) error

Send serializes a JSON msg using APIerror.Message and APIerror.Code and passes that to ctx.Send()

func (APIerror) With

func (e APIerror) With(s string) APIerror

With returns a copy of APIerror with the string appended at the end of e.Err

func (APIerror) WithErr

func (e APIerror) WithErr(err error) APIerror

WithErr returns a copy of APIerror with err.Error() appended at the end of e.Err

func (APIerror) Withf

func (e APIerror) Withf(format string, args ...any) APIerror

Withf returns a copy of APIerror with the Sprintf formatted string appended at the end of e.Err

type APIhandler

type APIhandler = func(*APIdata, *httprouter.HTTPContext) error

APIhandler is the handler function used by the bearer std API httprouter implementation