apiendpoint

Documentation

Overview

Package apiendpoint provides a lightweight API framework for use with River UI. It lets API endpoints be defined, then mounted into an http.ServeMux.

Index

• type Endpoint
  • func (e *Endpoint[TReq, TResp]) SetLogger(logger *slog.Logger)
  • func (e *Endpoint[TReq, TResp]) SetMeta(meta *EndpointMeta)
• type EndpointExecuteInterface
• type EndpointInterface
  • func Mount[TReq any, TResp any](mux *http.ServeMux, logger *slog.Logger, ...) EndpointInterface
• type EndpointMeta
• type RawExtractor
• type RawResponder

Types

type Endpoint

type Endpoint[TReq any, TResp any] struct {
	// contains filtered or unexported fields
}

Endpoint is a struct that should be embedded on an API endpoint, and which provides a partial implementation for EndpointInterface.

func (*Endpoint[TReq, TResp]) SetLogger

func (e *Endpoint[TReq, TResp]) SetLogger(logger *slog.Logger)

func (*Endpoint[TReq, TResp]) SetMeta

func (e *Endpoint[TReq, TResp]) SetMeta(meta *EndpointMeta)

type EndpointExecuteInterface

type EndpointExecuteInterface[TReq any, TResp any] interface {
	EndpointInterface

	// Execute executes the API endpoint.
	//
	// This should be implemented by each specific API endpoint.
	Execute(ctx context.Context, req *TReq) (*TResp, error)
}

EndpointExecuteInterface is an interface to an API endpoint. Some of it is implemented by an embedded Endpoint struct, and some of it should be implemented by the endpoint itself.

type EndpointInterface

type EndpointInterface interface {
	// Meta returns metadata about an API endpoint, like the path it should be
	// mounted at, and the status code it returns on success.
	//
	// This should be implemented by each specific API endpoint.
	Meta() *EndpointMeta

	// SetLogger sets a logger on the endpoint.
	//
	// Implementation inherited from an embedded Endpoint struct.
	SetLogger(logger *slog.Logger)

	// SetMeta sets metadata on an Endpoint struct after its extracted from a
	// call to an endpoint's Meta function.
	//
	// Implementation inherited from an embedded Endpoint struct.
	SetMeta(meta *EndpointMeta)
}

func Mount

func Mount[TReq any, TResp any](mux *http.ServeMux, logger *slog.Logger, apiEndpoint EndpointExecuteInterface[TReq, TResp]) EndpointInterface

Mount mounts an endpoint to a Go http.ServeMux. The logger is used to log information about endpoint execution.

type EndpointMeta

type EndpointMeta struct {
	// Pattern is the API endpoint's HTTP method and path where it should be
	// mounted, which is passed to http.ServeMux by Mount. It should start with
	// a verb like `GET` or `POST`, and may contain Go 1.22 path variables like
	// `{name}`, whose values should be extracted by an endpoint request
	// struct's custom ExtractRaw implementation.
	Pattern string

	// StatusCode is the status code to be set on a successful response.
	StatusCode int
}

EndpointMeta is metadata about an API endpoint.

type RawExtractor

type RawExtractor interface {
	ExtractRaw(r *http.Request) error
}

RawExtractor is an interface that can be implemented by request structs that allows them to extract information from a raw request, like path values.

type RawResponder

type RawResponder interface {
	RespondRaw(w http.ResponseWriter) error
}

RawResponder is an interface that can be implemented by response structs that allow them to respond directly to a ResponseWriter instead of emitting the normal JSON format.