httpjson

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

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

func Read(r io.Reader, v interface{}) error

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

func Request(ctx context.Context) *http.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

func WithRequest(ctx context.Context, req *http.Request) context.Context

WithRequest returns a context with an HTTP request stored in it. It is useful for testing.

func Write

func Write(ctx context.Context, w http.ResponseWriter, status int, v interface{})

Write sets the Content-Type header field to indicate JSON data, writes the header using status, then writes v to w. It logs any error encountered during the write.

Types

type ErrorWriter

type ErrorWriter func(context.Context, http.ResponseWriter, error)

ErrorWriter is responsible for writing the provided error value to the response.