api

Documentation

Index

• Variables
• func DecodeJSON[T any](request *http.Request) (T, error)
• func Error(status int, code string, message string) (response.Response, error)
• func JSON(status int, value any) (response.Response, error)
• func NoContent() response.Response
• func QueryBool(request *http.Request, name string) (bool, bool, error)
• func QueryInt(request *http.Request, name string) (int, bool, error)
• func QueryInt64(request *http.Request, name string) (int64, bool, error)
• func QueryString(request *http.Request, name string) (string, bool)
• func QueryStrings(request *http.Request, name string) []string
• func RequireJSONContentType(request *http.Request) error
• func ResultStatus(result any, fallback int) int
• type ErrorBody
• type ErrorInfo
• type Handler
• type JSONFieldDecoder
  • func NewJSONFieldDecoder(request *http.Request) (*JSONFieldDecoder, error)
  • func (decoder *JSONFieldDecoder) Bool(name string) (bool, error)
  • func (decoder *JSONFieldDecoder) Field() (string, error)
  • func (decoder *JSONFieldDecoder) Finish() error
  • func (decoder *JSONFieldDecoder) Int(name string, bitSize int) (int64, error)
  • func (decoder *JSONFieldDecoder) More() bool
  • func (decoder *JSONFieldDecoder) String(name string) (string, error)
  • func (decoder *JSONFieldDecoder) Strings(name string) ([]string, error)
  • func (decoder *JSONFieldDecoder) Uint(name string, bitSize int) (uint64, error)
  • func (decoder *JSONFieldDecoder) UnknownField(name string) error
• type Registry
• type StatusResult

Variables

var (
	// ErrNilRequest reports that a helper was called without an HTTP request.
	ErrNilRequest = errors.New("api request is nil")
	// ErrUnsupportedContentType reports a non-JSON request content type.
	ErrUnsupportedContentType = errors.New("unsupported API content type")
	// ErrMultipleJSONValues reports a JSON request body with trailing values.
	ErrMultipleJSONValues = errors.New("multiple JSON values in API request body")
)

Functions

func DecodeJSON

func DecodeJSON[T any](request *http.Request) (T, error)

DecodeJSON decodes a JSON request body into T. Unknown object fields are rejected so handler inputs stay explicit.

func Error

func Error(status int, code string, message string) (response.Response, error)

Error creates a structured JSON API error response.

func JSON

func JSON(status int, value any) (response.Response, error)

JSON creates a runtime response from a value encoded as JSON.

func NoContent

func NoContent() response.Response

NoContent creates an empty successful API response.

func QueryBool

func QueryBool(request *http.Request, name string) (bool, bool, error)

QueryBool returns the first query value for name as a bool.

func QueryInt

func QueryInt(request *http.Request, name string) (int, bool, error)

QueryInt returns the first query value for name as an int.

func QueryInt64

func QueryInt64(request *http.Request, name string) (int64, bool, error)

QueryInt64 returns the first query value for name as an int64.

func QueryString

func QueryString(request *http.Request, name string) (string, bool)

QueryString returns the first query value for name.

func QueryStrings

func QueryStrings(request *http.Request, name string) []string

QueryStrings returns all query values for name.

func RequireJSONContentType

func RequireJSONContentType(request *http.Request) error

RequireJSONContentType verifies that request declares a JSON media type.

func ResultStatus

func ResultStatus(result any, fallback int) int

ResultStatus returns result's APIStatus when it implements StatusResult.

Types

type ErrorBody

type ErrorBody struct {
	OK    bool      `json:"ok"`
	Error ErrorInfo `json:"error"`
}

ErrorBody is the default structured error payload for API helpers.

type ErrorInfo

type ErrorInfo struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorInfo describes one API error.

type Handler

type Handler func(http.ResponseWriter, *http.Request)

Handler is a generated API endpoint.

type JSONFieldDecoder

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

JSONFieldDecoder decodes one JSON object field at a time for generated API adapters. It accepts only a top-level object, preserves json.Number for integer parsing, and lets generated code reject unknown fields explicitly.

func NewJSONFieldDecoder

func NewJSONFieldDecoder(request *http.Request) (*JSONFieldDecoder, error)

NewJSONFieldDecoder creates a field decoder for a strict JSON object body.

func (*JSONFieldDecoder) Bool

func (decoder *JSONFieldDecoder) Bool(name string) (bool, error)

Bool decodes the next JSON field value as a bool.

func (*JSONFieldDecoder) Field

func (decoder *JSONFieldDecoder) Field() (string, error)

Field returns the next field name in the current JSON object.

func (*JSONFieldDecoder) Finish

func (decoder *JSONFieldDecoder) Finish() error

Finish consumes the object close token and rejects trailing JSON values.

func (*JSONFieldDecoder) Int

func (decoder *JSONFieldDecoder) Int(name string, bitSize int) (int64, error)

Int decodes the next JSON field value as a signed integer.

func (*JSONFieldDecoder) More

func (decoder *JSONFieldDecoder) More() bool

More reports whether the current JSON object has another field.

func (*JSONFieldDecoder) String

func (decoder *JSONFieldDecoder) String(name string) (string, error)

String decodes the next JSON field value as a string.

func (*JSONFieldDecoder) Strings

func (decoder *JSONFieldDecoder) Strings(name string) ([]string, error)

Strings decodes the next JSON field value as an array of strings.

func (*JSONFieldDecoder) Uint

func (decoder *JSONFieldDecoder) Uint(name string, bitSize int) (uint64, error)

Uint decodes the next JSON field value as an unsigned integer.

func (*JSONFieldDecoder) UnknownField

func (decoder *JSONFieldDecoder) UnknownField(name string) error

UnknownField returns the generated adapter error for an unsupported JSON object field. Generated adapters stop immediately, so no value is consumed.

type Registry

type Registry map[string]Handler

Registry maps generated API handler names to handlers.

type StatusResult

type StatusResult interface {
	APIStatus() int
}

StatusResult can be implemented by typed API result structs to choose the generated JSON response status without using the raw response.Response escape hatch. Non-positive values fall back to 200 OK.