negotiator

README

Negotiator

This is a libary that handles content negotiation in web applications written in Go.

Usage

Simple

To return JSON/XML out of the box simple put this in your route handler:

func getUser(w http.ResponseWriter, req *http.Request) {
    user := &User{"Joe","Bloggs"}
    if err := negotiator.Negotiate(w, req, user); err != nil {
      http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

Custom

To add your own negotiator, for example you want to write a PDF with your model, do the following:

1. Create a type that conforms to the ResponseProcessor interface

2. Call negotiator.New(responseProcessors ...ResponseProcessor) and pass in a your custom processor. When your request handler calls negotiator.Negotiate(w,req,model,errorHandler) it will render a PDF if your Accept header defined it wanted a PDF response.

Documentation

Overview

Package negotiator is a library that handles content negotiation in web applications written in Go. Content negotiation is specified by RFC (http://tools.ietf.org/html/rfc7231) and, less formally, by Ajax (https://en.wikipedia.org/wiki/XMLHttpRequest).

A Negotiator contains a list of ResponseProcessor. For each call to Negotiate, the best matching response processor is chosen and given the task of sending the response.

For more information visit http://github.com/jchannon/negotiator

func getUser(w http.ResponseWriter, req *http.Request) {
    user := &User{"Joe", "Bloggs"}
    negotiator.Negotiate(w, req, user)
}

Index

• Constants
• func IsAjax(req *http.Request) bool
• func Negotiate(w http.ResponseWriter, req *http.Request, dataModel interface{}, ...) error
• type AjaxResponseProcessor
• type ContentTypeSettable
• type Negotiator
  • func New(responseProcessors ...ResponseProcessor) *Negotiator
  • func NewWithJSONAndXML(responseProcessors ...ResponseProcessor) *Negotiator
  • func (n *Negotiator) Add(responseProcessors ...ResponseProcessor) *Negotiator
  • func (n *Negotiator) Negotiate(w http.ResponseWriter, req *http.Request, dataModel interface{}, ...) error
• type ResponseProcessor
  • func NewCSV(comma ...rune) ResponseProcessor
  • func NewJSON() ResponseProcessor
  • func NewJSONIndent(prefix, index string) ResponseProcessor
  • func NewJSONIndent2Spaces() ResponseProcessor
  • func NewTXT() ResponseProcessor
  • func NewXML() ResponseProcessor
  • func NewXMLIndent(prefix, index string) ResponseProcessor
  • func NewXMLIndent2Spaces() ResponseProcessor

Constants

const (
	// ParameteredMediaRangeWeight is the default weight of a media range with an
	// accept-param
	ParameteredMediaRangeWeight float64 = 1.0 //e.g text/html;level=1
	// TypeSubtypeMediaRangeWeight is the default weight of a media range with
	// type and subtype defined
	TypeSubtypeMediaRangeWeight float64 = 0.9 //e.g text/html
	// TypeStarMediaRangeWeight is the default weight of a media range with a type
	// defined but * for subtype
	TypeStarMediaRangeWeight float64 = 0.8 //e.g text/*
	// StarStarMediaRangeWeight is the default weight of a media range with any
	// type or any subtype defined
	StarStarMediaRangeWeight float64 = 0.7 //e.g */*
)

Functions

func IsAjax

func IsAjax(req *http.Request) bool

IsAjax tests whether a request has the Ajax header.

func Negotiate

func Negotiate(w http.ResponseWriter, req *http.Request, dataModel interface{}, context ...interface{}) error

Negotiate your model based on the HTTP Accept header. Only XML and JSON are handled.

Types

type AjaxResponseProcessor

type AjaxResponseProcessor interface {
	IsAjaxResponder() bool
}

AjaxResponseProcessor interface allows content negotiation to be biased when Ajax requests are handled. If a ResponseProcessor also implements this interface and its method returns true, then all Ajax requests will be fulfilled by that request processor, instead of via the normal content negotiation.

type ContentTypeSettable

type ContentTypeSettable interface {
	SetContentType(contentType string) ResponseProcessor
}

ContentTypeSettable interface provides for those response processors that allow the response Content-Type to be set explicitly.

type Negotiator

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

Negotiator is responsible for content negotiation when using custom response processors.

func New

func New(responseProcessors ...ResponseProcessor) *Negotiator

New allows users to pass custom response processors.

func NewWithJSONAndXML

func NewWithJSONAndXML(responseProcessors ...ResponseProcessor) *Negotiator

NewWithJSONAndXML allows users to pass custom response processors. By default, processors for XML and JSON are already created.

func (*Negotiator) Add

func (n *Negotiator) Add(responseProcessors ...ResponseProcessor) *Negotiator

Add more response processors. A new Negotiator is returned with the original processors plus the extra processors.

func (*Negotiator) Negotiate

func (n *Negotiator) Negotiate(w http.ResponseWriter, req *http.Request, dataModel interface{}, context ...interface{}) error

Negotiate your model based on the HTTP Accept header.

type ResponseProcessor

type ResponseProcessor interface {
	CanProcess(mediaRange string) bool
	Process(w http.ResponseWriter, req *http.Request, dataModel interface{}, context ...interface{}) error
}

ResponseProcessor interface creates the contract for custom content negotiation.

func NewCSV

func NewCSV(comma ...rune) ResponseProcessor

NewCSV creates an output processor that serialises a dataModel in CSV form. With no arguments, the default format is comma-separated; you can supply any rune to be used as an alternative separator.

Model values should be one of the following:

* string or []string, or [][]string

* fmt.Stringer or []fmt.Stringer, or [][]fmt.Stringer

* []int or similar (bool, int8, int16, int32, int64, uint8, uint16, uint32, uint63, float32, float64, complex)

* [][]int or similar (bool, int8, int16, int32, int64, uint8, uint16, uint32, uint63, float32, float64, complex)

* struct for some struct in which all the fields are exported and of simple types (as above).

* []struct for some struct in which all the fields are exported and of simple types (as above).

func NewJSON

func NewJSON() ResponseProcessor

NewJSON creates a new processor for JSON without indentation.

func NewJSONIndent

func NewJSONIndent(prefix, index string) ResponseProcessor

NewJSONIndent creates a new processor for JSON with a specified indentation.

func NewJSONIndent2Spaces

func NewJSONIndent2Spaces() ResponseProcessor

NewJSONIndent2Spaces creates a new processor for JSON with 2-space indentation.

func NewTXT

func NewTXT() ResponseProcessor

NewTXT creates an output processor that serialises strings in text/plain form. Model values should be one of the following:

* string

* fmt.Stringer

* encoding.TextMarshaler

func NewXML

func NewXML() ResponseProcessor

NewXML creates a new processor for XML without indentation.

func NewXMLIndent

func NewXMLIndent(prefix, index string) ResponseProcessor

NewXMLIndent creates a new processor for XML with a specified indentation.

func NewXMLIndent2Spaces

func NewXMLIndent2Spaces() ResponseProcessor

NewXMLIndent2Spaces creates a new processor for XML with 2-space indentation.