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

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

Functions

func Mount

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

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

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 EndpointInterface

type EndpointInterface[TReq any, TResp any] interface {
	// Execute executes the API endpoint.
	//
	// This should be implemented by each specific API endpoint.
	Execute(ctx context.Context, req *TReq) (*TResp, error)

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

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