Documentation
¶
Overview ¶
Package responders provides HTTP response helpers for JSON APIs.
Use this package to handle the common patterns of decoding request parameters, invoking a callback, and writing the response. The responders automatically handle parameter validation, JSON encoding, and error responses.
The JSON responder encodes a response body as JSON. The JSONStream responder streams multiple JSON objects using chunked transfer encoding. The Status responder returns only an HTTP status code without a body. The Error responder converts errors to appropriate HTTP status codes and JSON error messages.
Custom error types can be registered with MustRegisterErrorResponse to map specific error types to HTTP status codes and formatted error messages. Unregistered errors default to HTTP 500 Internal Server Error.
Index ¶
- func Error(writer http.ResponseWriter, err error, opts ...Option)
- func JSON[RequestParameters any, ResponseBody any](writer http.ResponseWriter, request *http.Request, ...)
- func JSONStream[RequestParameters any, ResponseBody any](writer http.ResponseWriter, request *http.Request, ...)
- func MustRegisterErrorResponse[T any](status int, callback func(err *T) *StandardErrorResponse)
- func Status[RequestParameters any](writer http.ResponseWriter, request *http.Request, ...)
- type Option
- type StandardErrorResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Error ¶
func Error(writer http.ResponseWriter, err error, opts ...Option)
Error responds to an HTTP requests with an ErrorResponse. It tries to match it to a known error type so it can return its corresponding status and message. It defaults to HTTP 500 internal server error.
func JSON ¶
func JSON[RequestParameters any, ResponseBody any]( writer http.ResponseWriter, request *http.Request, callback func(*RequestParameters) (*ResponseBody, int, error), opts ...Option, )
JSON responds to an HTTP request by encoding the response as JSON.
func JSONStream ¶
func JSONStream[RequestParameters any, ResponseBody any]( writer http.ResponseWriter, request *http.Request, callback func(*RequestParameters) (<-chan *ResponseBody, int, error), opts ...Option, )
JSONStream responds to an HTTP request by streaming responses as JSON objects. The producer is responsible for closing the response channel.
func MustRegisterErrorResponse ¶
func MustRegisterErrorResponse[T any](status int, callback func(err *T) *StandardErrorResponse)
MustRegisterErrorResponse allows error types to be registered for the Error responder. The registered error type should always be instantiated as a pointer for this to work correctly.
Types ¶
type Option ¶
type Option func(*config)
Option configures the responders.
func WithErrorCallback ¶
WithErrorCallback configures the responder to invoke this callback when a responder processing error occurs. Do not retry any HTTP responder when this is invoked.
type StandardErrorResponse ¶
type StandardErrorResponse struct {
Message string `json:"message"`
}
StandardErrorResponse is the standard JSON response an API endpoint makes when an error occurs in the endpoint handler.
Source Files