Documentation ¶
Overview ¶
Package httpjson creates HTTP handlers to map request and response formats onto Go function signatures. The request body is decoded as a JSON text into an arbitrary value and the function's return value is encoded as a JSON text for the response body. The function's signature determines the types of the input and output values.
For example, the handler for a function with signature
func(struct{ FavColor, Birthday string })
would read the JSON request body into a variable of type struct{ FavColor, Birthday string }, then call the function.
The allowed elements of a function signature are:
parameters: Context (optional) request body (optional) return values: response body (optional) error (optional)
All elements are optional. Thus, the smallest possible function signature is
func()
If the function returns a non-nil error, the handler will call the error function provided in its constructor. Otherwise, the handler will write the return value as JSON text to the response body. If the return type is omitted, the handler will send a default response value.
Index ¶
- Variables
- func Array(v interface{}) interface{}
- func Handler(f interface{}, errFunc ErrorWriter) (http.Handler, error)
- func Read(r io.Reader, v interface{}) error
- func Request(ctx context.Context) *http.Request
- func ResponseWriter(ctx context.Context) http.ResponseWriter
- func WithRequest(ctx context.Context, req *http.Request) context.Context
- func Write(ctx context.Context, w http.ResponseWriter, status int, v interface{})
- type ErrorWriter
Constants ¶
This section is empty.
Variables ¶
var DefaultResponse = json.RawMessage(`{"message":"ok"}`)
DefaultResponse will be sent as the response body when the handler function signature has no return value.
var ErrBadRequest = errors.New("httpjson: bad request")
ErrBadRequest indicates the user supplied malformed JSON input, possibly including a datatype that doesn't match what we expected.
Functions ¶
func Array ¶
func Array(v interface{}) interface{}
Array returns an empty JSON array if v is a nil slice, so that it renders as "[]" rather than "null". Otherwise, it returns v.
func Handler ¶
func Handler(f interface{}, errFunc ErrorWriter) (http.Handler, error)
Handler returns an HTTP handler for function f. See the package doc for details on allowed signatures for f. If f returns a non-nil error, the handler will call errFunc.
func Read ¶
Read decodes a single JSON text from r into v. The only error it returns is ErrBadRequest (wrapped with the original error message as context).
func Request ¶
Request returns the HTTP request stored in ctx. If there is none, it panics. The context given to a handler function registered in this package is guaranteed to have a request.
func ResponseWriter ¶
func ResponseWriter(ctx context.Context) http.ResponseWriter
ResponseWriter returns the HTTP response writer stored in ctx. If there is none, it panics. The context given to a handler function registered in this package is guaranteed to have a response writer.
func WithRequest ¶
WithRequest returns a context with an HTTP request stored in it. It is useful for testing.
Types ¶
type ErrorWriter ¶
type ErrorWriter func(context.Context, http.ResponseWriter, error)
ErrorWriter is responsible for writing the provided error value to the response.