respond

README

respond

• v1 has been released
• Read the blog post 'API responses in Go' for an in-depth overview

Get it:

go get gopkg.in/matryer/respond.v1

Import it:

import (
  "gopkg.in/matryer/respond.v1"
)

Use it:

respond.With(w, r, http.StatusOK, data)

Package respond provides low-touch API responses for Go data services.

• Idiomatic way of responding to data APIs using respond.With
• Use respond.With to respond with default options, or make a respond.Options for advanced features
• Encoder abstraction lets you easily speak different formats
• Before and After function fields allow you to envelope and mutate data, set common HTTP headers, log activity etc.
• Protected against multiple responses

Usage

The simplest use of respond is to just call respond.With inside your handlers:

func handleSomething(w http.ResponseWriter, r *http.Request) {
	
	data, err := loadFromDB()
	if err != nil {

		// respond with an error
		respond.With(w, r, http.StatusInternalServerError, err)
		return // always return after responding

	}

	// respond with OK, and the data
	respond.With(w, r, http.StatusOK, data)

}

To tweak the behaviour of respond.With you can wrap the handler with a respond.Options:

func main() {
	
	opts := &respond.Options{
		// options go here
	}
	http.Handle("/foo", opts.Handler(fooHandler))
	log.Fatal(http.ListenAndServe(":8080", nil))

}

Use respond.With as normal.

For a complete list of options, see the API documentation for respond.Options.

Documentation

Overview

Package respond provides low-touch idiomatic API responses for Go.

Index

• func With(w http.ResponseWriter, r *http.Request, status int, data interface{})
• func WithStatus(w http.ResponseWriter, r *http.Request, status int)
• type Encoder
• type Options
  • func (o *Options) Handler(handler http.Handler) http.Handler
  • func (o *Options) OnErrLog(err error)

Functions

func With

func With(w http.ResponseWriter, r *http.Request, status int, data interface{})

With responds to the client.

func WithStatus

func WithStatus(w http.ResponseWriter, r *http.Request, status int)

WithStatus responds to the client with the specified status. Options.StatusData will be called to obtain the data payload, or a default payload will be returned:

{"status":"I'm a teapot","code":418}

Types

type Encoder

type Encoder interface {
	// Encode writes a serialization of v to w, optionally using additional
	// information from the http.Request to do so.
	Encode(w http.ResponseWriter, r *http.Request, v interface{}) error
	// ContentType gets a string that will become the Content-Type header
	// when responding through w to the specified http.Request.
	// Most of the time the argument will be ignored, but occasionally
	// details in the request, or even in the headers in the ResponseWriter may
	// change the content type.
	ContentType(w http.ResponseWriter, r *http.Request) string
}

Encoder descirbes an object capable of encoding a response.

var JSON Encoder = (*jsonEncoder)(nil)

JSON is an Encoder for JSON.

type Options

type Options struct {
	// AllowMultiple indicates that multiple responses are allowed. Otherwise,
	// multiple calls to With will panic.
	AllowMultiple bool

	// OnErr is a function field that gets called when an
	// error occurs while responding.
	// By default, the error panic but you may
	// use Options.OnErrLog to just log the error out instead,
	// or provide your own.
	OnErr func(err error)

	// Encoder is a function field that gets the encoder to
	// use to respond to the specified http.Request.
	// If nil, JSON will be used.
	Encoder func(w http.ResponseWriter, r *http.Request) Encoder

	// Before is called for before each response is written
	// and gives user code the chance to mutate the status or data.
	// Useful for handling different types of data differently (like errors),
	// enveloping the response, setting common HTTP headers etc.
	Before func(w http.ResponseWriter, r *http.Request, status int, data interface{}) (int, interface{})

	// After is called after each response.
	// Useful for logging activity after a response has been written.
	After func(w http.ResponseWriter, r *http.Request, status int, data interface{})

	// StatusData is a function field that gets the data to respond with when
	// WithStatus is called.
	// By default, the function will return an object that looks like this:
	//     {"status":"Not Found","code":404}
	StatusData func(w http.ResponseWriter, r *http.Request, status int) interface{}
}

Options provides additional control over the behaviour of With.

func (*Options) Handler

func (o *Options) Handler(handler http.Handler) http.Handler

Handler wraps an HTTP handler becoming the source of options for all containing With calls.

func (*Options) OnErrLog

func (o *Options) OnErrLog(err error)

OnErrLog prints a log out with the specified error. It is an option for Options.OnErr.